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
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).
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/companiescom as mesmas chaves: use oiddo CNPJ desejado.
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
{
"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.