📘

O que você irá aprender com esse artigo?

• Tipos de autenticação
• Diferenças entre os tokens
• Criando suas chaves de API via painel
• Como criar os tokens via API
• Como utilizar o live_token e o test_token
• Assinatura de Requisições (RSA)

Tipos de autenticação

A autenticação na iugu é realizada por meio de uma chave de API, que permite ao sistema identificar a sua conta e conceder as permissões necessárias para a comunicação com a iugu em nome da conta associada.

Existem três métodos de autenticação disponíveis, sendo o mais recomendado o uso do HTTP Basic Auth. A segunda opção é a autenticação por Bearer Authentication. A terceira alternativa é enviar o API Token como um parâmetro denominado api_token.

live_token, test_token e user_token

1. live_token: utilize-o para ações em ambiente produção.

2. test_token: utilize-o para ações em ambiente de teste (homologação/sandbox).

3. user_token: utilize-o para requisições às APIs:

   API Token

   API	Endpoint
   Criar API Token	v1/{account_id}/api_tokens
   Remover API Token	v1/{account_id}/api_tokens/{id}
   Renovar API Token de Usuário	v1/profile/renew_access_token
   Listar API Tokens das subcontas	v1/retrieve_subaccounts_api_token

   Subconta

   API	Endpoint
   Atualizar Subconta	v1/accounts/{id}
   Enviar verificação de Subconta	v1/accounts/{account_id}/request_verification

Como ter acesso ao user_token?

1. No retorno 200 OK do endpoint Criar Subconta — v1/marketplace/create_account.
2. Ou no retorno 200 OK do endpoint Listar API Tokens das subcontas — v1/retrieve_subaccounts_api_token.

🚧

Importante

• Os endpoints Criar Subconta e Listar API Tokens das subcontas são requisitadas, exclusivamente, pela Conta Mestre.
• Utilize o live_api_token

Criar api_token

Há duas formas de criar um api_token:

1. Via Alia
2. Via API

Alia

1. Acesse alia.iugu.com > Configurações
2. Integrações API > Novo
3. Escolha entre Teste ou Produção
4. Dê uma descrição. Por exemplo: "Minha chave API"
5. Clique em Salvar.

🚧

Importante

• Este api_token ficará visível por apenas 1h. Após isso, será censurado.
• A criação de api_tokens dependem de uma aprovação enviada para os Administradores da Conta.

API

Utilize o endpoint Criar API Token — v1/{account_id}/api_tokens.

Request e Response exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/id-da-conta/api_tokens?api_token=api_token' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "api_type": "TEST",
  "description": "Minha chave API de Teste"
}
'

{
  "id": "A0036E328D254004AEA7FD9FE808CDA5",
  "token": "048e378481b750ffbc3ab9e0c0fee11",
  "api_type": "TEST",
  "description": "Minha chave API de Teste",
  "created_at": "2024-06-16T13:31:04-03:00"
}

Dica de segurança 🔐

Recomendamos a atualização da sua chave de API a cada 30 dias. Manter a chave atualizada é fundamental para evitar seu uso indevido em caso de vazamento de informações.

Não se esqueça de que sua chave de API funciona como uma senha, sendo ela responsável por autorizar suas transações de forma automática e autenticada.

Como utilizar o live_token e o test_token

HTTP Basic Auth

Para gerar o header de autenticação HTTP Basic da request, deve-se seguir os seguintes passos:

1. Ter a chave API, seja de teste ou de Produção

2. Codificar a chave API, junto com o caracter “:” no final da chave, para o formato Base64. Exemplo: 5AA555555555555555555555555555555CC55555555555555555555555555DD5:
   Base64 dessa chave: NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=

3. No header, inserir o campo de “Authorization”, seguido com o valor que é a chave API codificada
   Exemplo: --header 'Authorization: Basic NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=

Modelo de request

curl --location --request GET 'https://api.iugu.com/v1/customers' 
--header 'Accept: application/json' 
--header 'Content-Type: application/json' 
--header 'Authorization: Basic {apitoken in base64}' 
--header 'Cookie: __cfruid=df598e45cd90947e522e12ec895a84f7059cacbc-1627922464' 
--data-raw ''

Parâmetro api_token

As requests permitem o envio de um parâmetro chamado api_token, onde pode ser enviado o API Token gerado anteriormente em vez de utilizar o HTTP Basic Auth.

Bearer Authentication

Há a possibilidade também de utilizar a autenticação Bearer.

Para gerar o header de autenticação HTTP Bearer, deve-se seguir os seguintes passos:

1. Ter a chave API, seja de teste ou de Produção

2. Codificar a chave API, junto com o caracter “:” no final da chave, para o formato Base64. Exemplo: 5AA555555555555555555555555555555CC55555555555555555555555555DD5:
   Base64 dessa chave: NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=

3. No header, inserir o campo de “Authorization”, seguido com o valor que é a chave API codificada
   Exemplo: --header 'Authorization: Bearer NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=

Modelo de Request

curl --location --request GET 'https://api.iugu.com/v1/customers' \ 
--header 'Accept: application/json' 
--header 'Content-Type: application/json' 
--header 'Authorization: Basic {apitoken in base64}' 
--header 'Cookie: __cfruid= 95dfe99ff2d3d94d649675cf8cb7491b4bda25b7-1641564409' \ 
--data-raw ''

Autenticação com Assinatura RSA

O que é Assinatura RSA?

Uma Assinatura RSA em APIs é um método de criptografia que utiliza o algoritmo RSA para garantir a autenticidade e a integridade das mensagens trocadas entre um cliente e um servidor. Ela envolve a criação de uma assinatura digital usando uma chave privada, que pode ser verificada por qualquer pessoa com a chave pública correspondente. Isso assegura que a mensagem foi enviada por uma fonte confiável e que não foi alterada durante a transmissão.

Endpoints obrigatórios

Os endpoints que têm como características Cash Out requerem, obrigatoriamente, essa autenticação. São eles:

Bibliotecas

Como alternativa do fluxo manual deste artigo, utilize as nossas bibliotecas: Biblioteca RSA. As linguagens disponíveis são:

• Ruby
• Java
• Node.js
• PHP
• Pyton

Prefere um vídeo ensinando como faz?

Assista nosso Webinar conduzido por um dos nossos Engenheiros:

Que tal uma Recipe?🧪

Aqui está uma sugestão de como o seu script (em Ruby) pode ser desenvolvido:

Antes de começar ⚠️

Alguns pontos importantes antes de começar:

1. É possível apenas em produção (live_mode)
2. É permitido apenas um api_token criptografado por conta.
3. Necessário ter acesso ao Alia para a etapa de criação do api_token.
   1. Não é possível utilizar o endpoint Criar API Token — v1/{account_id}/api_tokens como alternativa.
4. Este processo exige a utilização de OpenSSL.
5. Crie uma pasta que armazenará os arquivos do OpenSSL.
6. Navegue até esta pasta utilizando o cmd

Após estas etapas, continue com este artigo.

Usuários Linux

Comandos de copy serão utilizados neste passo a passo. Certifique-se de que o xclip ou xsel está instalado no seu sistema. Você pode instalar com:

$ sudo apt-get install xclip

ou

$ sudo apt-get install xsel

Fluxo Whitelabel

Para estruturas de Marketplace (subcontas), é possível seguir as etapas deste guia e refletir para as subcontas atreladas à Mestre, descartando a necessidade de fazê-la uma a uma.

Para isso, siga as etapas de 1 a 4 na Conta Mestre e, nas etapas de 5 a 12, e onde for solicitado o "api_token criptografado", insira o live_api_token da subconta, por mais que ele não seja criptografado.

Ilustração do Fluxo

O que precisará ter?

• Uma subconta com um live_api_token
• A Conta Mestre desta Subconta com um api_token criptografado.

Continue com este artigo.

1. Gerar chave privada

No cmd, insira este comando:

$ openssl genrsa -out private.pem 2048

2. Gerar chave pública

Ainda no cmd, insira o comando abaixo para gerar a chave pública a partir da chave privada

$ openssl rsa -in private.pem -outform PEM -pubout -out public.pem

3. Copiar a chave pública

Copie para o clipboard a chave pública gerada:

Windows

$ clip < public.pem

macOS

$ pbcopy < public.pem

Linux (xclip)

xclip -selection clipboard < public.pem

Linux (xsel)

$ xsel --clipboard < public.pem

4. Colar chave pública no painel

1. Acesse alia.iugu.com
2. Configurações > Integrações via API
3. Clique em Novo > e, em Tipo, selecione Produção
4. Dê uma descrição para esta chave (exemplo: Minha chave RSA)
5. Abaixo de descrição, cole a chave pública mantendo os cabeçalhos ----BEGIN PUBLIC KEY---- e ----END PUBLIC KEY----
6. Clique em Salvar.

Esta chave será identificada como Chave criptografada.

🚧

Importante

• A criação de api_tokens dependem de uma aprovação enviada para os Administradores da Conta.
• Guarde o api_token gerado em um lugar seguro

Body = raw

Assine o corpo da requisição de forma bruta (raw), sem qualquer tratamento ou parse. O payload assinado deve ser idêntico ao enviado na requisição. A assinatura gerada deve ser criptografada em base64 e incluída na requisição.

O restante permanece inalterado: o corpo da requisição deve conter o api_token e todos os campos necessários, sem qualquer alteração no processo usual.

❗️

Quebra de Linhas

Ao montar o arquivo no Windows, não utilize editores no terminal, como Vim, Nano, etc. Qualquer espaço, aspas, quebra de linha, invalidará a requisição.

Recomendamos a utilização de editores de texto como Notepad++, VSCode ou, até mesmo, o próprio Bloco de Notas, que permitem a visualização das quebras das delinha CR LF, LF e CR, que variam entre Sistemas Operacionais.

5. Assinar e enviar requisição

Com a chave criptografada criada em sua conta (etapa 1 ao 4), continue com este artigo para a Assinatura da Requisição.

Atenção ⚠️

As próximas etapas servem para simular os processos técnicos e o seu resultado. A forma de implantá-la fica à critério do cliente/seller.

As etapas de 5 ao 12 devem ser realizadas para todas as requisições, sem exceção.

Timestamp padrão ISO8061 e UTC

O timestamp segue os padrões ISO8061. O UTC deve ser o mesmo do servidor que esta solução será hospedada.

Utilize os comandos abaixo para gerar um timestamp nos padrões ISO8061:

macOS

date +"%Y-%m-%dT%H:%M:%S%Z:00"

Linux

date +"%Y-%m-%dT%H:%M:%S%:z"

🚧

Tolerância de 5 minutos

O timestamp inserido no documento tem uma tolerância de até 5 minutos. Por exemplo: 2024-06-15T12:55:00-03:00, só é possível enviar a requisição até 12:59:59. Se exceder, retornará Invalid Signature

5.1 Criar arquivo .txt

1. Crie um arquivo .txt com nome 'documento' em sua pasta (etapa 5 de Atenção ⚠️)
2. Para cada endpoint, escreva o body no 'documento', seguindo, exatamente, os padrões a seguir:

Importante ⚠️

A linha 3 não deve conter nenhum espaço, a não ser que seja o valor de um parâmetro, por exemplo "Nome da Subconta". Este pode conter espaços, pois é um valor e não interferirá.

O resultado do exemplo acima é:

POST|/v1/signature/validate
1AB1CD2EF1BC9DE0165FC37268331E1A4A0D8FCF90E2C42AB4100CBDB86E5136|2024-06-15T12:21:29-03:00
{"name":"Nome da Subconta","splits":[{"recipient_account_id":"account_id","cents":20}]}

Observações — Whitelabel

• Na linha 2: Substitua o api_tokencriptografado pelo live_api da subconta.

Exemplos de documento.txt de cada endpoint

Os scripts abaixo são exemplos de como o seu documento deve ser escrito para ser assinado:

Transferir Valor — POST v1/transfers

POST|/v1/transfers
api_tokencriptografado|2024-06-15T12:21:29-03:00
{"receiver_id":"id-da-conta","amount_cents":100}

Transferência para Terceiros — POST v1/transfers_requests

POST|/v1/transfer_requests
api_tokencriptografado|2024-06-15T12:21:29-03:00
{"receiver":{"pix":{"type":"email","key":"[email protected]"},"name":"Nome","cpf_cnpj":"113.436.750-30"},"transfer_type":"pix","amount_cents":100}

Pedido de Saque/Transferências Próprias — POST v1/accounts/{id}/request_withdraw

POST|/v1/accounts/id-da-subconta/request_withdraw
api_tokencriptografado|2024-06-15T12:21:29-03:00
{"amount":10}

Validate Signature — POST v1/signature/validate

POST|/v1/signature/validate
api_tokencriptografado|2024-06-15T12:21:29-03:00
{"RAW_BODY":"string"}

Criar Subconta — POST v1/marketplace/create_account

POST|/v1/marketplace/create_account
api_tokencriptografado|2024-06-15T12:21:29-03:00
{"name":"Nome da Subconta","splits":[{"recipient_account_id":"account_id","cents":20}]}

Configurar Conta — POST v1/accounts/configuration

POST|/v1/accounts/configuration
api_tokencriptografado|2024-06-15T12:21:29-03:00
{"auto_withdraw":true,"auto_advance":false}

Adicionar domicílio bancário — POST /v1/bank_verification

POST|/v1/bank_verification
api_tokencriptografado|2024-06-15T12:21:29-03:00
{"agency":"0000","account":"000000","account_type":"cc","bank":"001"}

Criar Pedido de Pagamento — POST v1/payment_requests

POST|/v1/payment_requests
api_tokencriptografado|2024-06-15T12:21:29-03:00
{"barcode":"846100000013310502962023004200030007003752691117","document_amount_cents":10,"amount_cents":10}

5.2 Salvar arquivo

Após informações inseridas, salve este arquivo e não altere-o mais.

6. Assinar documento.txt usando Chave privada

No cmd, insira o seguinte comando:

openssl dgst -sha256 -sign private.pem -out sign.sha256 documento.txt

7. Transformar em base64

Insira o comando abaixo para transformar (encode) para base64 o conteúdo do arquivo sign.sha256 de sua pasta:

openssl base64 -A -in sign.sha256 -out sign.sha256.base64

📘

sign.sha256.base64

Após executá-lo, cria-se um novo arquivo de nome sign.sha256.base64 na mesma pasta.

8. Copiar conteúdo sign.sha256.base64

Insira o comando para copiar para o clipboard o conteúdo que será utilizado no header — Signature — da requisição

Windows

clip < sign.sha256.base64

macOS

$ pbcopy < sign.sha256.base64

Linux (xclip)

xclip -selection clipboard < sign.sha256.base64

Linux (xsel)

$ xsel --clipboard < sign.sha256.base64

9. Preparar o URL

Utilize um dos endpoints (de acordo com a etapa 5.1) que deseja e atente-se às seguintes informações:

Neste exemplo, foi escolhido o endpoint de Transferência para Terceiros — v1/transfer_requests, então, preencha de acordo com a sua requisição:

https://api.iugu.com/v1/transfer_requests?api_token=api_tokencriptografado

10. Copiar o body do documento.txt

Copie apenas a terceira linha do documento.txt:

{"receiver_id":"id-da-conta","amount_cents":100,"api_token":"api_tokencriptografado"}

Como o header deve ficar?

Preencha os parâmetros do header no padrão 'parâmetro=valor' de acordo com estas instruções:

11. Colar o conteúdo no body

Com o conteúdo do body copiado (etapa 10), cole no corpo da requisição.

🚧

Verifique se houve alteração

Alguns editores de texto formatam os arquivos por padrão e isso poderá invalidar a assinatura (Invalid Signature). Se alterado, utilize o Bloco de Notas, VSCode ou Notepad++.

12. Enviar requisição

Certifique-se de ter seguido estritamente todos os passos deste guia e, por fim, requisite o endpoint escolhido.

Verificar se assinatura é válida (opcional)

Utilize o endpoint Validate Signature — v1/signature/validate para verificar se a assinatura gerada (etapa 7 e 8) é válida. Ou seja, esta rota não torna uma assinatura válida, apenas a verifica.

Este endpoint segue a mesma lógica das etapas 5 até 12, então, siga-os para requisitá-lo.

Request e Response exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/signature/validate?api_token=api_tokencriptografado' \
     --header 'Request-Time: 2024-06-15T12:21:29-03:00' \
     --header 'Signature: signature=sequência-de-caracteres' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{"RAW_BODY": "teste validação"}
,

{
  "message": "Signature check successful",
  "request_body": "{\n  \"api_token\":\"<api_token-criptografado>\",\n  \"message\":\"anything\"\n}",
  "status": "ok"
}

Signature check successful

O retorno "message": "Signature check successful" serve apenas para validar que o seu script seguiu a lógica correta.

Importante ⚠️

Este é o único endpoint que o Fluxo Whitelabel não é compatível.

Erros

Os erros de criptografia são sucintos por, justamente, serem criptografados. Apesar disso, há erros que têm uma explicação. Veja-os abaixo:

Referências técnicas

Algumas referências para fins de conhecimento:

• Basic Auth
• Manual Base64
• Bearer Authentication
• Padrão ISO 8601 para tempo (inglês)
• Gerar chave RSA pelo terminal (inglês)