Pular para o conteúdo
Orbasy Fiscal
EntrarCriar conta
API a partir do plano Pro, webhooks em todos os planos

Emita pelo seu sistema, em JSON

A mesma API que o painel usa, documentada em OpenAPI. Você cria a nota com o ID do seu pedido, emite em fila ou esperando a SEFAZ e recebe cada mudança de status por webhook assinado.

Criar contaFalar com vendas
criar-nota.shbash
curl -X POST "$ORBASY_API_URL/api/v1/invoices" \
  -H "x-api-key: $ORBASY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "externalId": "pedido-1042",
    "companyId": "ext:loja-centro",
    "modelo": "65",
    "naturezaOperacao": "Venda ao consumidor",
    "tipoOperacao": "1",
    "destinoOperacao": "1",
    "indIntermed": "0",
    "codigoMunicipioFG": "4205407",
    "items": [{
      "codigoProduto": "CAFE-500",
      "descricao": "Café torrado 500 g",
      "ncm": "09012100",
      "cfop": "5102",
      "unidade": "UN",
      "quantidade": 2,
      "valorUnitario": 18.9,
      "icmsOrigem": "0"
    }],
    "pagamentos": [{ "tipoPagamento": "17", "valorPagamento": 37.8 }]
  }'
Criação, emissão e o webhook de uma NFC-e autorizada.
escopos para limitar cada chave
30
eventos de webhook
17
tentativas de entrega por evento
8
de log de cada entrega
30 dias

Como funciona

  1. Crie uma chave

    O administrador escolhe os escopos e a validade. A chave aparece uma vez e fica guardada só como hash.

  2. Crie a nota com o seu ID

    O externalId do seu pedido vira o endereço da nota nas rotas, com ext: na frente.

  3. Emita

    Em fila, com resposta imediata, ou com ?sync=1 para esperar o protocolo da SEFAZ.

  4. Receba o webhook

    Cada mudança de status chega assinada no seu endpoint, com reenvio se ele não responder.

O que o módulo de API e webhooks faz

API REST com chaves de escopo e webhooks assinados com reenvio.

  • Chaves com escopo

    30 escopos, validade e revogação. Só o administrador gerencia as chaves.

  • Os seus IDs

    Use ext:<seu-id> em qualquer rota. Um externalId repetido devolve 409 com o registro que já existe.

  • OpenAPI

    Cada rota documentada, com os exemplos e os erros que ela pode devolver.

  • Erros com a regra

    A recusa fiscal vem com o cStat, a regra de validação, o campo e a sugestão de correção.

  • Rate limit por organização

    O limite vale para a organização, e cada resposta traz os headers com o que resta.

  • Webhooks

    17 eventos de NF-e, NFC-e, NFS-e e DF-e, com filtro por evento em cada endpoint.

  • Assinatura HMAC

    O header X-Orbasy-Signature traz o horário e a assinatura HMAC-SHA256 do corpo.

  • Reenvio e teste

    Reenvie uma entrega pelo log, dispare um ping de teste e troque o segredo quando quiser.

  • Endpoints protegidos

    Só HTTPS, sem endereços internos, e o endpoint que falha demais é desativado.

Uma chave para cada integração

Cada chave vai no header x-api-key e carrega só os escopos que a integração precisa. O plano Pro inclui 3 chaves e o Max 10. A chave pode ter validade e ser revogada a qualquer momento.

  • Chave exibida uma vez e guardada como hash
  • Escopos de leitura e de escrita separados por recurso
  • Rotas que falam com a SEFAZ com limite próprio
  • Paginação com até 100 registros por página

Erros que dizem o que corrigir

Uma nota recusada pela validação volta com 422, o código da rejeição que a SEFAZ daria, a regra de validação do manual, o campo e a sugestão de correção do catálogo.

  • Sugestão de correção para os 547 códigos de retorno catalogados
  • Avisos que não bloqueiam voltam na nota, separados dos erros
  • Um externalId repetido devolve 409 com o registro existente
resposta-422.jsonjson
{
  "statusCode": 422,
  "error": "FiscalError",
  "codigo": "ZFM_SUFRAMA_EMITENTE_INVALIDO",
  "message": "Rejeição 1186 (C22-20): dígito verificador da inscrição SUFRAMA do emitente inválido",
  "cStat": "1186",
  "rv": "C22-20",
  "campo": "suframa",
  "sugestao": "Verifique a Inscrição SUFRAMA cadastrada para a empresa — o dígito verificador não confere."
}

Webhooks em que dá para confiar

A entrega espera uma resposta 2xx em até 10 segundos. Sem ela, o evento é reenviado até 8 vezes com espera progressiva. Cada evento tem um id próprio, para o seu sistema descartar uma entrega repetida.

  • Até 5 endpoints ativos por organização
  • Desativação depois de 20 falhas seguidas
  • Log de cada entrega por 30 dias
  • Horário assinado, para recusar entregas com mais de 5 minutos
verificar-a-assinatura.tsts
import { createHmac, timingSafeEqual } from "node:crypto";

// header: X-Orbasy-Signature, no formato t=<unix>,v1=<hex>
export function isValidSignature(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((pair) => pair.split("=")));
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const received = String(parts.v1 ?? "");
  return received.length === expected.length && timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

Especificações

Formato
REST com JSON
Autenticação
Header x-api-key, com escopos
Chaves
3 no Pro e 10 no Max
Documentação
OpenAPI, com as rotas, os exemplos e os erros
Erros fiscais
422 com cStat, regra, campo e sugestão
Webhooks
17 eventos, HMAC-SHA256, 8 tentativas
Entrega
Ao menos uma vez, com id por evento

Perguntas sobre API e webhooks

  • A partir do Pro. Os webhooks funcionam em todos os planos, inclusive para quem emite só pelo painel.

Ainda tem uma dúvida?Fale com a nossa equipe.

Funciona junto com

Teste em homologação antes de ir para produção

Assine um plano, cadastre a empresa e emita notas de teste. Em homologação, as notas não consomem a cota do plano.

Criar contaVer planos