Regulariza API Service

Introdução

Documentação para integração aos serviços da plataforma Regulariza.

Características do serviço

O serviço utiliza a arquitetura REST (Representational State Transfer), que utiliza os verbos HTTP (GET, POST, PUT e DELETE) para executar as operações. A API suporta os formatos JSON e XML, definidos através do cabeçalho HTTP "content-type":

Para formato JSON

content-type:application/json

accept:application/json

Para formato XML

content-type:application/xml

accept:application/xml

O protocolo padrão para comunicação com as APIs REST é HTTP 1.1 e a codificação de caracteres é UTF-8.

Requisições

Todas as requisições devem conter o cabeçalho de autorização HTTP com os dados de acesso (login e senha) de um tipo de usuário WebService que é fornecido pela Regulariza. Isto garante o uso correto do sistema e identificação de quem está realizando o pedido.

Os dados de acesso, devem estar codificados em base 64 com o formato LOGIN:SENHA

Exemplo, se o login é "0123ABCDEF" e a senha é "A1B2C3D4E5", o cabeçalho de autorização deve ser o seguinte:

Authorization: Basic <base64 of 0123ABCDEF:A1B2C3D4E5>

Authorization: Basic MDEyM0FCQ0RFRjpBMUIyQzNENEU1

Exemplo de cabeçalho de requisição:

POST http://api.regulariza.co.ao/api/SimulacaoAcordoService HTTP/1.1
accept-encoding: gzip,deflate
accept-language: pt-br
content-type: application/json
accept: application/json
content-length: 771
host: api.regulariza.co.ao
connection: keep-alive
authorization: Basic MDEyM0FCQ0RFRjpBMUIyQzNENEU1

O corpo da requisição é definido conforme o tipo de serviço solicitado.

A resposta do serviço contém o código do erro (00 para mensagem de sucesso, 88 para mensagem de negócio e 99 para mensagem de erro), criticas e dados.

O JSON abaixo exemplifica uma resposta do serviço.

{
  "cod": 0,
  "criticas": [
    {
      "critica": "sample string 1"
    },
    {
      "critica": "sample string 1"
    }
  ],
  "dados": {
    "acordos": {...}
  }
}

Instruções sobre preenchimento de objetos:

• Formato JSON
  
  • Atributos não declarados no corpo da requisição serão desprezados.
  • Atributos preenchidos com null ou "", serão desprezados.
  • Valores numéricos maiores que 1 não devem iniciar com 0 (zero). Exemplos de valores não permitidos: "0123", "010.25", "03.45".
• Formato XML
  
  • Atributos não declarados no corpo da requisição serão desprezados
  • Atributos declarados com conteúdo vazio, invalidarão a requisição
  • Ao alterar a ordem de declaração de um determinado atributo, o conteúdo de todos os atributos predecessores serão interpretado como nulo
• Verbo PUT (Atualização de dados)
  
  • Atributos preenchidos com "-1" (para tipos numéricos, enumeradores e string) e "01-01-0001" (para tipo datetime), serão interpretados como uma solicitação de nulidade

A estrutura completa que compõe o corpo das requisições de envio e retorno é descrita no tópico "Métodos", deste documento.

Pré-requisitos

• O cadastro da empresa deverá estar ativo junto á Regulariza.
• Os dados de acesso (login e senha) devem ser de um usuário do tipo WebService, fornecido à empresa pela Regulariza.
• O usuário WebService cadastrado na Regulariza deverá estar com status "ativo" na Regulariza.
• O usuário WebService cadastrado na Regulariza deverá ter permissão para realizar as ações previstas pelo serviço (inclusão, alteração e consulta).

Endpoints

Ambiente de Produção

URL: https://api.regulariza.co.ao/

Ambiente de Homologação

URL: https://homologaapi.regulariza.co.ao/

Exemplos de código

C#

using System;
using System.Net;
using System.Text;
namespace API_REGULARIZA_Exemplo_CSharp
{
class Program
{
    const string USUARIO = "usuario";
    const string SENHA = "123456";
    const string ENDPOINT = "URL";
    static void Main(string[] args)
    {
        //Consultando um contrato
        string metodo = ENDPOINT + "/api/ContratoService?CodContrato=999999";
        string resultado = GetData(metodo);
        Console.WriteLine("Resultado consulta contrato: " + resultado);
            
        //Incluindo um contrato
        string jsonRequest = "{""dados"":{""contrato"":{""numerocontrato"":""220024"",""codcarteira"":5157,""codproduto"":4854,""datacontratual"":"""",""datacorte"":"""",""codfasecobranca"":2,""score"":""012"",""tipopessoa"":""F"",""nomedevedor"":""João de Sá Cavalcanti"",""cpfcnpj"":""10342666169"",""rg"":""9999999999"",""rgorgaoexpedidor"":"""",""sexo"":""M"",""estadocivil"":""C"",""qtdfilho"":1,""nacionalidade"":""Brasileiro"",""naturalidade"":""Soteropolitano"",""pai"":""Antônio Carlos"",""mae"":""Lívia Aparecida"",""datanascimento"":""27/11/1988"",""profissao"":""Dentista"",""empresa"":""Sorriso Saúde ME"",""dataadmissao"":""11/08/2014"",""ocupacao"":""Médico"",""cargo"":""Cirurgião"",""renda"":""9525.00"",""escolaridade"":""Superior C"",""codstatusdevedor"":1,""titulos"":[{""codtipo"":1,""codstatustitulo"":1,""numerotitulo"":""001"",""vencimentotitulo"":""14/07/2017"",""valortitulo"":""741.00""},{""codtipo"":1,""codstatustitulo"":1,""numerotitulo"":""002"",""vencimentotitulo"":""14/08/2017"",""valortitulo"":""741.00""},{""codtipo"":1,""codstatustitulo"":1,""numerotitulo"":""003"",""vencimentotitulo"":""14/08/2017"",""valortitulo"":""52.00""}]}}}";
        metodo = ENDPOINT + "/api/ContratoService";
        resultado = PostData(metodo, jsonRequest);
        Console.WriteLine("Resultado inclusão contrato: " + resultado);
        Console.ReadKey();
    }
    /// <summary>
    /// Efetua uma requisição para o verbo GET, com basic authentication
    /// </summary>
    /// <param name="pUrl">URL completa (Endpoint + método)</param>
    /// <returns>A resposta contém o código do erro (00, 88 ou 99), críticas e dados.</returns>
    static private string GetData(string pUrl)
    {
        string resultado = "";
        try
        {
            ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
            using (var client = new WebClient())
            {
                client.Headers.Add("Authorization", "Basic " + Base64Encode(USUARIO + ":" + SENHA));
                client.Headers.Add(HttpRequestHeader.ContentType, "application/json");
                client.Encoding = Encoding.UTF8;
            
                resultado = client.DownloadString(pUrl);
            }
        }
        catch (WebException ex)
        {
            resultado = new System.IO.StreamReader(ex.Response.GetResponseStream()).ReadToEnd();
        }
        return resultado;
    }
    /// <summary>
    /// Efetua uma requisição para o verbo POST, com basic authentication
    /// </summary>
    /// <param name="pUrl">URL completa (Endpoint + método)</param>
    /// <param name="pData">JSON contendo os dados para inclusão</param>
    /// <returns>A resposta contém o código do erro (00, 88 ou 99), críticas e dados.</returns>
    static private string PostData(string pUrl, string pData)
    {
        string resultado = "";
        try
        {
            ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
            using (var client = new WebClient())
            {
                client.Headers.Add("Authorization", "Basic " + Base64Encode(USUARIO + ":" + SENHA));
                client.Headers.Add(HttpRequestHeader.ContentType, "application/json");
                client.Encoding = Encoding.UTF8;
                resultado = client.UploadString(pUrl, "POST", pData);
            }
        }
        catch (WebException ex)
        {
            resultado = new System.IO.StreamReader(ex.Response.GetResponseStream()).ReadToEnd();
        }
        return resultado;
    }
    /// <summary>
    /// Converte texto para base64
    /// </summary>
    /// <param name="plainText">texto</param>
    /// <returns>Retorna um string em base 64 </returns>
    static private string Base64Encode(string plainText)
    {
        var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(plainText);
        return System.Convert.ToBase64String(plainTextBytes);
    }
}
}            
            

VB.NET

Imports System.Net
Imports System.Text
Module Module1
    Const USUARIO As String = "usuario"
    Const SENHA As String = "123456"
    Const ENDPOINT As String = "URL"
    Sub Main()
        'Consultando um contrato
        Dim metodo As String = ENDPOINT & "/api/ContratoService?CodContrato=999999"
        Dim resultado As String = GetData(metodo)
        Console.WriteLine("Resultado consulta contrato: " & resultado)
        'Incluindo um contrato
        Dim jsonRequest As String = "{""dados"":{""contrato"":{""numerocontrato"":""220024"",""codcarteira"":5157,""codproduto"":4854,""datacontratual"":"""",""datacorte"":"""",""codfasecobranca"":2,""score"":""012"",""tipopessoa"":""F"",""nomedevedor"":""João de Sá Cavalcanti"",""cpfcnpj"":""10342666169"",""rg"":""9999999999"",""rgorgaoexpedidor"":"""",""sexo"":""M"",""estadocivil"":""C"",""qtdfilho"":1,""nacionalidade"":""Brasileiro"",""naturalidade"":""Soteropolitano"",""pai"":""Antônio Carlos"",""mae"":""Lívia Aparecida"",""datanascimento"":""27/11/1988"",""profissao"":""Dentista"",""empresa"":""Sorriso Saúde ME"",""dataadmissao"":""11/08/2014"",""ocupacao"":""Médico"",""cargo"":""Cirurgião"",""renda"":""9525.00"",""escolaridade"":""Superior C"",""codstatusdevedor"":1,""titulos"":[{""codtipo"":1,""codstatustitulo"":1,""numerotitulo"":""001"",""vencimentotitulo"":""14/07/2017"",""valortitulo"":""741.00""},{""codtipo"":1,""codstatustitulo"":1,""numerotitulo"":""002"",""vencimentotitulo"":""14/08/2017"",""valortitulo"":""741.00""},{""codtipo"":1,""codstatustitulo"":1,""numerotitulo"":""003"",""vencimentotitulo"":""14/08/2017"",""valortitulo"":""52.00""}]}}}"
        
        metodo = ENDPOINT & "/api/ContratoService"
        resultado = PostData(metodo, jsonRequest)
        Console.WriteLine("Resultado inclusão contrato: " & resultado)
        Console.ReadKey()
    End Sub
    ''' <summary>
    ''' Efetua uma requisição para o verbo GET, com basic authentication
    '''</summary>
    ''' <param name="pUrl">URL completa (Endpoint + método)</param>
    ''' <returns>A resposta contém o código do erro (00, 88 ou 99), críticas e dados.</returns>
    Private Function GetData(ByVal pUrl As String) As String
        Dim resultado As String = ""
        Try
            ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12
            Using client = New WebClient()
                client.Headers.Add("Authorization", "Basic " & Base64Encode(USUARIO & ":" & SENHA))
                client.Headers.Add(HttpRequestHeader.ContentType, "application/json")
                client.Encoding = Encoding.UTF8
                resultado = client.DownloadString(pUrl)
            End Using
        Catch ex As WebException
            resultado = New System.IO.StreamReader(ex.Response.GetResponseStream()).ReadToEnd()
        End Try
        Return resultado
    End Function
    ''' <summary>
    ''' Efetua uma requisição para o verbo POST, com basic authentication
    ''' </summary>
    ''' <param name="pUrl">URL completa (Endpoint + método)</param>
    ''' <param name="pData">JSON contendo os dados para inclusão</param>
    ''' <returns>A resposta contém o código do erro (00, 88 ou 99), críticas e dados.</returns>
    Private Function PostData(ByVal pUrl As String, ByVal pData As String) As String
        Dim resultado As String = ""
        Try
            ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12
            Using client = New WebClient()
                client.Headers.Add("Authorization", "Basic " & Base64Encode(USUARIO & ":" & SENHA))
                client.Headers.Add(HttpRequestHeader.ContentType, "application/json")
                client.Encoding = Encoding.UTF8
                resultado = client.UploadString(pUrl, "POST", pData)
            End Using
        Catch ex As WebException
            resultado = New System.IO.StreamReader(ex.Response.GetResponseStream()).ReadToEnd()
        End Try
        Return resultado
    End Function
    ''' <summary>
    ''' Converte texto para base64
    ''' </summary>
    ''' <param name="plainText">texto</param>
    ''' <returns>Retorna um string em base 64 </returns>
    Private Function Base64Encode(ByVal plainText As String) As String
        Dim plainTextBytes = System.Text.Encoding.UTF8.GetBytes(plainText)
        Return System.Convert.ToBase64String(plainTextBytes)
    End Function
End Module