Chaves de API

Uma chave de API permite que seu back-end trabalhe com uma loja. Crie-a no painel, salve-a no seu servidor e a envie como um token bearer.

Crie uma chave

Na loja, crie uma chave com as permissões read e write. O token ivk_ é exibido uma única vez; salve-o imediatamente. Uma loja pode ter até 10 chaves que não estejam revogadas; veja Limites.

Um agente pode criar a mesma chave usando sua sessão de login:

curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/keys' \
  -H 'Authorization: Bearer <session-token>' \
  -H 'Idempotency-Key: <saved-unique-key>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"backend","scopes":["read","write"]}'

Use uma sessão para criar ou alterar chaves. Uma chave de API não pode criar outra chave. Se a conta tiver MFA, o gerenciamento de chaves pode exigir um segundo fator recente.

Chame a API

curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/payments?limit=50' \
  -H 'Authorization: Bearer ivk_...'

Escopo	Finalidade
read	permite ler faturas e depósitos.
write	permite criar faturas e depósitos e gerenciar webhooks.

Solicite as duas permissões para um back-end que cria pagamentos e os verifica. Não presuma que write inclui read automaticamente.

A chave só funciona dentro das permissões da sua loja. Ela não pode gerenciar contas ou a equipe do lojista. Nunca a coloque em código de navegador, uma URL de pagamento ou um chat compartilhado.

Restrinja o acesso por IP

Opcionalmente, forneça allowed_ips ao criar ou editar uma chave:

{"allowed_ips":["203.0.113.10","2001:db8::/32"]}

Estes são endereços de exemplo. Substitua-os pelos endereços de saída reais do seu back-end. São permitidos até 10 IPs ou faixas CIDR por chave; mais do que isso retorna 400 too_many_allowed_ips. Uma lista vazia remove a restrição.

Rotacione ou revogue

Crie uma chave substituta, atualize seu back-end e depois revogue a chave antiga com DELETE /api/v1/shops/{shop_id}/keys/{key_id}.

PATCH no mesmo caminho pode alterar name, enabled, scopes ou allowed_ips. Campos omitidos permanecem inalterados. A edição não revela nem rotaciona o token.

As chaves funcionam até serem desativadas ou revogadas, sujeitas ao acesso da conta e da loja. Elas não são uma promessa de acesso permanente. Veja a referência da API para os detalhes das requisições.