Autenticação

A Emitfy usa autenticação por chave de API da assinatura/conta. Envie em cada requisição: X-Api-Key e X-Api-Secret.

Headers

Shell
X-Api-Key: <api-key>
X-Api-Secret: <secret>

Empresa no path

O escopo da empresa é o segmento /v1/companies/:companyId/... (o companyId é o UUID da empresa retornado em GET /v1/companies, não o CNPJ) na URL — emissão e catálogo. A mesma credencial da assinatura serve para todas as empresas com acesso.

Webhooks e rotação de keys não usam companyId na URL (prefixo /v1/webhooks).

Shell
curl -X POST https://api.emitfy.com/v1/companies/{companyId}/nfe \
  -H "X-Api-Key: $EMITFY_API_KEY" \
  -H "X-Api-Secret: $EMITFY_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Onde encontro o companyId?

O companyId é o UUID da empresa na Emitfy — não é o CNPJ. Obtenha de um destes jeitos:

  • Painel → API & Webhooks, bloco Company ID (com seletor quando a conta tem mais de uma empresa).
  • GET /v1/companies com as mesmas chaves: use o id do CNPJ desejado.
Shell
curl https://api.emitfy.com/v1/companies \
  -H "X-Api-Key: $EMITFY_API_KEY" \
  -H "X-Api-Secret: $EMITFY_API_SECRET"

# { "success": true, "data": [ { "id": "01a17883-...", "taxId": "11.222.333/0001-81", ... } ] }

CNPJ no lugar do UUID retorna 400 INVALID_COMPANY_ID; um UUID que não é da sua conta (ou é de outro ambiente, produção × sandbox) retorna 404 COMPANY_NOT_FOUND.

Sandbox

O sandbox (https://api-sandbox.emitfy.com) tem contas e chaves próprias, criadas em app-sandbox.emitfy.com. Chaves e companyId de produção não funcionam no sandbox, e vice-versa. Toda emissão lá é em homologação.

Gerar credenciais

No painel: API & Webhooks (hub da assinatura). O X-Api-Key é o id do usuário; o secret é exibido só na geração/rotação.

Resposta de credenciais inválidas

JSON
{
  "success": false,
  "error": {
    "code": "INVALID_API_CREDENTIALS",
    "message": "Credenciais de API inválidas."
  }
}

Rate limit

O limite de requisições varia conforme o seu plano. Ao exceder, a resposta será 429 Too Many Requests com o header Retry-After.