Referências Técnicas

Introdução à API

A MOVA disponibiliza uma interface de programação baseada no REST e por meio dessa interface é feita a comunicação com o HUB de Integração.

A comunicação com nossos sistemas é feita através das URLs:

• Produção:https://api3.mova.vc/v1/hub/
• Staging:https://api3-staging.mova.vc/v1/hub

Comunicação com JSON

A comunicação com as APIs da MOVA é feita com JSON (JavaScript Object Notation). Ele é um formato leve e simples de realizar a leitura.

Vantagens

1. Simples de realizar a transformação de JSON para Objeto, e vice-versa.
2. Leitura mais simples.
3. Utilizado amplamente no mercado.

Erros

Algumas falhas podem acontecer durante a integração com as APIs. Abaixo estão detalhados os possíveis erros, seus respectivos status codes e como proceder para corrigi-los.

Possíveis erros

Como corrigir

Autenticação

Autenticação com API Key

Para que a comunicação com as APIs seja feita com sucesso, é necessário efetuar uma etapa de autenticação.

Como conseguir?

A chave é fornecida pela MOVA. Para conseguir uma chave você deve entrar em contato com o suporte, informando:

1. As APIs que irá utilizar
2. O ambiente (Staging ou Produção)
3. Dados do usuário solicitante (nome e email)
4. Dados da empresa solicitante (razão social e CNPJ)

Como utilizar?

A autenticação é feita através de um campo no header da requisição: x-apikey com a chave fornecida pela MOVA.

Exemplo:

curl -X POST https://api3.mova.vc/v1/hub/exemplo \
  -H "Content-Type: application/json" \
  -H "x-apikey: SUA_API_KEY_AQUI" \
  -d '{ ... }'

Identificação de Cliente (mova-client-id)

Para que a comunicação com as APIs seja feita com sucesso, é necessário efetuar uma etapa de identificação.

Como conseguir?

A chave é gerada para o cliente durante o processo de Onboarding, dessa forma nenhuma solicitação é necessária.

Como utilizar?

A identificação é feita através de um campo no header da requisição: mova-client-id com a chave fornecida pela MOVA.

Exemplo:

curl -X POST https://api3.mova.vc/v1/hub/exemplo \
  -H "Content-Type: application/json" \
  -H "x-apikey: SUA_API_KEY_AQUI" \
  -H "mova-client-id: SEU_CLIENT_ID_AQUI" \
  -d '{ ... }'

Requisições

Requisição Síncrona

Uma das formas de comunicação com as APIs da MOVA é por requisições síncronas, ou seja, a resposta vem no mesmo momento em que a solicitação foi feita.

Como funciona?

As chamadas síncronas são constituídas por uma requisição (chamada) e pela resposta da chamada. Um exemplo disso é a solicitação de uma simulação, onde você faz uma chamada, aguarda por um tempo e em seguida recebe a resposta dessa solicitação com sucesso ou com erro.

Algumas endpoints têm como padrão a requisição assíncrona, caso o cliente não informe que deseja utilizar a síncrona. Essa informação é enviada pelo cabeçalho da requisição (header), através do campo sync. Caso o valor informado no campo sync seja true, a requisição será síncrona.

Exemplo:

curl -X POST https://api3.mova.vc/v1/hub/exemplo \
  -H "Content-Type: application/json" \
  -H "x-apikey: SUA_API_KEY_AQUI" \
  -H "mova-client-id: SEU_CLIENT_ID_AQUI" \
  -H "sync: true" \
  -d '{ ... }'

Requisição Assíncrona

Outra forma de comunicação com as APIs da MOVA é através de requisições assíncronas, ou seja, a resposta esperada pode vir depois de um tempo e é recebida através de webhooks.

Como funciona?

Ao invés de ser realizada uma chamada síncrona (onde você já recebe a resposta "na hora"), com a requisição assíncrona você solicita que um processamento seja feito (como solicitar uma cotação), e assim que estiver concluído, a MOVA realizará uma chamada para a URL informada com os dados.

Algumas endpoints têm como padrão a requisição assíncrona. Essa informação é enviada pelo cabeçalho da requisição (header), através do campo sync. Caso o valor informado no campo sync seja false, a requisição será assíncrona.

Exemplo de requisição:

curl -X POST https://api3.mova.vc/v1/hub/exemplo \
  -H "Content-Type: application/json" \
  -H "x-apikey: SUA_API_KEY_AQUI" \
  -H "mova-client-id: SEU_CLIENT_ID_AQUI" \
  -H "sync: false" \
  -d '{ ... }'

Exemplo de resposta assíncrona (webhook):

{
  "api_version": "1.1.0",
  "transaction_id": "707xaf60-1d8c-481d-910b-8cbe1f00a57e",
  "data": {
    "general_info": {
      "response_type": "RETORNO_NEGOCIACAO_ATUALIZADA"
    },
    "borrower_info": {
      "cpf_cnpj": "12345678999",
      "name": "João Silva"
    },
    "proposal_info": [
      {
        "proposal_status": "INADIMPLENTE",
        "operation_tracking_id": "bjx837f2-d746-41fc-fd23-6d72b93d0385",
        "proposal_id": 124451,
        "product_id": 593,
        "registration_info": [
          {
            "contract_id": "C18663W15031S12441",
            "investment_amount": 2591.35,
            "investor_id": "12345678999"
          }
        ]
      }
    ],
    "general_installments_info": {
      "installments_number": 1,
      "sum_installments_principal_amount": 1036.36,
      "sum_installments_interest_amount": 27.98,
      "sum_installments_amount": 1064.35,
      "sum_installments_updated_amount": 2406.74
    },
    "individual_installments_info": [
      {
        "proposal_id": 124451,
        "installment_id": 5629033,
        "installment_status": "INADIMPLENTE",
        "installment_number": 3,
        "installment_due_date": "2022-07-01",
        "installment_principal_amount": 1036.36,
        "installment_interest_amount": 27.98,
        "installment_base_amount": 1064.35,
        "installment_updated_amount": 2406.74
      }
    ]
  }
}

As respostas desejadas serão obtidas posteriormente através de um webhook que lançará uma chamada para a URL do parceiro, que deverá ser cadastrada previamente. Consulte a seção sobre Webhooks abaixo.

Webhooks

Uma forma de realizar comunicação entre sistemas, de forma assíncrona e passiva, onde o requisitante não precisa aguardar, na mesma chamada que fez, os dados solicitados ou o resultado de uma operação. Assim você recebe uma chamada assim que um evento acontece como, por exemplo: solicitou uma cotação e então recebeu os dados dessa cotação via webhook.

Vantagens

1. Operação em tempo real
2. Economia (não é necessário realizar polling)
3. Agilidade na comunicação de sistemas

Como registrar?

Para que sejam configurados os endereços, durante o processo de Onboarding, devem ser informados:

• Endereço (URL)
• Forma de autenticação:
  • API Key — caso seja essa a escolhida, deve ser informado o método/verbo HTTP para autenticar.
  • OAuth 2.0
• Payload:
  • Padrão MOVA
  • Customizado

Webhooks disponíveis

Cotação

Status:

• Criada
• Reprovada
• Pendente
• Cancelada

Documento:

• Aprovado
• Reprovado

Pagamento

Parcela:

• Atualizada
• Baixada (Pagamento)
• Baixada (Renegociação)
• Atrasada
• Contrato Consolidado (Renegociação)
• Erro de Processamento

Proposta

Status:

• Aprovada
• Reprovada
• Cancelada
• Em assinatura
• Confirmar contrato
• Em liquidação
• Liquidada
• Quitada

Recebíveis:

• Trava Fumaça — CIP
• Trava Geral — CERC