API-First & Developer Portal

Documentação para Desenvolvedores

Conecte e-commerce, CRMs, Zapier, n8n e sistemas proprietários usando API Keys M2M seguras.

Autenticação por API Key M2M

Comunicação segura Machine-to-Machine de longa duração

Para integrações externas, o Yonk ERP utiliza o padrão de **API Keys M2M (`yk_live_...`)**. Cada chave é gerada com 256 bits de entropia e criptografada via hash de via única **SHA-256** no banco de dados.

Header X-API-Key (Recomendado)

X-API-Key: yk_live_a8f3c91d_9xK2mP...

Header Authorization Bearer

Authorization: Bearer yk_live_a8f3c91d...

Endurecimento de Segurança: URLs não criptografadas (`http://`) e endereços locais (`localhost`, `127.0.0.1`) são terminantemente proibidos para webhooks e integrações externas. Todas as chamadas devem usar HTTPS com suporte a TLS 1.3.

Endpoints de Integração Externa (`/v1/external/*`)

POST /v1/external/vendas/pedidos

Criação de Pedidos (E-Commerce & CRMs)

Recebe vendas vindas do Shopify, VTEX, Mercado Livre ou WooCommerce. Cadastra o cliente e produtos automaticamente e gera o orçamento/pedido no ERP.

GET /v1/external/estoque/saldos

Consulta de Estoque em Tempo Real

Retorna o saldo total, reservado e quantidade disponível para venda de todos os produtos do catálogo por código/SKU.

POST /v1/external/webhooks/subscriptions

Webhooks Push Notificações

Assine eventos M2M em tempo real (`pedido.criado`, `nfe.autorizada`, `titulo.pago`) com validação de assinatura HMAC-SHA256 no header `X-Yonk-Signature`.

GET /v1/external/vendas/pedidos/:id

Consulta de Status de Pedido

Verifica se um pedido foi aprovado, faturado ou transmitido para a SEFAZ.

Exemplo de Requisição (cURL)cURL

curl -X POST https://yonk-backend.onrender.com/v1/external/vendas/pedidos \
  -H "Content-Type: application/json" \
  -H "X-API-Key: yk_live_a8f3c91d_9xK2mP7qL4vR8tY1wZ5bN3jH6sD0fG2a" \
  -d '{
    "branchId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "clienteCnpjCpf": "12345678000195",
    "clienteRazaoSocial": "Empresa Cliente LTDA",
    "itens": [
      {
        "codigoProduto": "PROD-001",
        "quantidade": 5,
        "precoUnitario": 120.50
      }
    ]
  }'