Primeiros Passos

O acesso à nossa API Pública é feito via API Key, gerada manualmente pelo usuário no painel da plataforma. A chave identifica o ambiente em que ela atua. Este guia cobre o básico para sua primeiro "Hello World".

1. Gerando sua API Key

Antes de começar você deverá:

1. Acessar o painel web da plataforma e fazer login com seu email e senha.
2. Ir em Configurações → API Keys.
3. Selecionar o ambiente:
   • test — para integração e desenvolvimento.
   • live — produção.
4. (Opcional) Definir um rótulo para identificar a chave.
5. Clicar em Gerar nova chave.

Atenção: A chave em texto pleno é exibida uma única vez no momento da criação. Copie e armazene em um cofre de segredos imediatamente. Caso perca, será necessário gerar uma nova.

A Base URL do ambiente de Produção é https://api.somosmarcha.com/api/v1/.

2. Formato da Chave

Toda chave segue o formato:

mk_<environment>_<token>

Exemplos:

mk_live_aB3xyZ9f7G2H1jK4mN6pQ8rT0vW2YZaC
mk_test_dE5fgH7i8J0kL2mN4oP6qR8sT0uV2wXa

• O prefixo mk_ permite que ferramentas de secret scanning (GitHub, GitGuardian, etc.) detectem vazamentos automaticamente.
• O segmento live ou test indica o ambiente — chaves de ambientes diferentes não são intercambiáveis.

3. Autenticando Requests

Envie a chave no header Authorization em todas as requisições:

curl --request GET \
  --url https://api.somosmarcha.com/api/v1/finance/balance/ \
  --header 'Authorization: Bearer mk_live_aB3xyZ9f7G2H1jK4mN6pQ8rT0vW2YZaC' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json'

Atenção: Caso o header Authorization não seja enviado, ou a chave esteja revogada/inválida, uma resposta 401 Unauthorized será retornada.

{
  "message": "Credenciais invalidas."
}

4. Boas Práticas de Segurança

• Nunca comite a chave em repositórios de código. Use variáveis de ambiente ou um gerenciador de segredos.
• Use mk_test_ durante desenvolvimento e CI; só promova para mk_live_ no ambiente de produção.
• Revogue imediatamente qualquer chave que possa ter vazado (logs públicos, screenshot, repositório aberto). A revogação é instantânea — a chave para de funcionar na próxima request.
• Uma chave por integração: cada usuário tem uma única chave ativa por ambiente. Gerar uma nova chave revoga a anterior automaticamente.
• Limite de requisições: a API aplica rate limiting de 300 requests/minuto por chave. Picos acima disso retornam 429 Too Many Requests.

5. Códigos de Erro Recorrentes

A API preza por respostas semânticas, mantendo alta previsibilidade sobre o que pode ter ocorrido mal durante uma chamada:

Status HTTP	O que significa?
20X	Operação efetuada com sucesso (200 OK, 201 Created ou 204 No Content).
400	Bad Request — Algum parâmetro de POST ou GET foi enviado no formato incorreto.
401	Unauthorized — A chave de API está ausente, inválida ou revogada.
403	Forbidden — A chave é válida mas não tem permissão sobre o recurso solicitado.
404	Not Found — O objeto buscado (ex: Pedido por UUID) não existe.
429	Too Many Requests — Limite de requisições por minuto excedido. Reduza a taxa e tente novamente.
50X	Exceções não contornadas do nosso lado do servidor (acione o suporte enviando os IDs das requisições ocorridas).