API Documentos Contables

De WikiSerpi
(Redirigido desde «API Documentos-Contables»)
Ir a la navegación Ir a la búsqueda

Descripción: Esta API permite la sincronizacion de documentos contables entre SERPI y la plataforma que lo requiera permitiendo tener un manejo estandar entre las dos herramientas.

Autorización: Se requiere autenticación para todas las solicitudes. Las credenciales de autenticación deben ser incluidas en la cabecera de todas las solicitudes a través del campo Authorization utilizando el token de acceso entregado SERPI ERP.

Beneficio:

Tipos de peticiones: GET, POST, PUT

¿Cómo funciona?

  • Tenga en cuenta que un mismo token no puede ser consumidos de manera simultanea, por lo cual puede programar que la siguiente API sea consumida cuando el resultado de la anterior sea exitoso.
  • En términos de tiempo, para hacer seguimiento a su operación puede hacer un consumo cada 5 minutos de la información.

Métodos

<Tabs> <Tab name = "API Consulta Tipos de Documento"> GET/users

EndPoint: https://www.apis.serpi.com.co/api/v1/DocumentoContable/GetTipoDocumento


Headers

Header Descripción
secretkey Secretkey proporcionada al cliente para consumos de las APIs

Authorization: 

Usar Bearer. Ejemplo “bearer {{token}}”.
{{token}} Token de autorizacion generado por SerpiERP

Parámetros

Parámetro Tipo de dato Requerido Descripción
Límite int No Este parámetro indica la cantidad de resultados que se deben devolver en una sola página
Página int No Este parámetro indica el número de la página que se debe devolver. Por ejemplo, si se establece en 3, se devolverán los resultados de la tercera página

Response 

{
    "success": true,
    "code": 200,
    "errors": null,
    "message": "2 registro(s) encontrados",
    "result": [
        {
            "id": 1,
            "categoriaDocumento": "NC",
            "prefijo": "RCA",
            "descripcion": "RECIBO DE CAJA"
        },
        {
            "id": 2,
            "categoriaDocumento": "NC",
            "prefijo": "NCC",
            "descripcion": "NOTA CONTABLE"
        }
    ]
}

{
    "success": true,
    "code": 204,
    "message": "No se encontraron registros",
}

Campo de resultados

Campo Tipo de dato Descripción
id int Corresponde al identificador del tipo de documento
categoriaDocumento string Categoría del tipo de documento
prefijo string Prefijo del tipo de documento
descripcion string Descripción del tipo de documento

</Tab>

<Tab name = "API Consultar Documentos Contables"> POST /users

EndPoint: https://www.apis.serpi.com.co/api/v1/DocumentoContable/ConsultarDocumentoContables?limite=10&pagina=1

Headers

Header Descripción
secretkey Secretkey proporcionada al cliente para consumos de las APIs

Body: 

{
    "tiposDocumentos": [15,16],
    "numeroDesde": null,
    "numeroHasta": null,
    "fechaDesde": "2023-01-01",
    "fechaHasta": "2023-01-31"
}

Campos del request

Campo Tipo Requerido Descripción
tiposDocumentos Array [Int] SI Array de enteros. Son los Ids de los tipos de documentos (Api Consulta tipos documento)
numeroDesde int NO Numero inicial para filtrar por rango de números de documentos
numeroHasta int NO Numero final para filtrar por rango de números de documentos
fechaDesde string SI Fecha inicial para filtrar por rango de fecha del documento
fechaHasta bool SI Fecha final para filtrar por rango de fecha del documento


Authorization: 

Usar Bearer. Ejemplo “bearer {{token}}”.
{{token}} Token de autorizacion generado por SerpiERP

Response 

{
    "success": true,
    "code": 200,
    "errors": null,
    "message": "1 registro(s) encontrados",
    "result": [
        {
            "id": 111,
            "categoriaDocumento": "CCO",
            "prefijo": "COM",
            "numeroDoc": 1,
            "nitTerceroEnc": "1234567890",
            "nombreTerceroEnc": "ALEJANDRA LOPEZ LOPEZ",
            "fechaDocumento": "2023-03-01",
            "detalles": [
                {
                    "cuenta": 52954501,
                    "nitTerceroDet": "1234567890",
                    "nombreTerceroDet": "ALEJANDRA LOPEZ LOPEZ",
                    "naturaleza": "D",
                    "crucePrefijo": null,
                    "cruceNumero": null,
                    "fechaVencimiento": null,
                    "valor": 67900.00000,
                    "baseImpuesto": 0.00000,
                    "cuota": 0,
                    "detalle": "SERV DE TRANSP INFORMAL",
                    "idSubcentroCosto": 4,
                    "idCentroOperacion": 1,
                    "idProyecto": null,
                    "idActividad": null,
                    "idSucursal": null
                },
                {
                    "cuenta": 23359501,
                    "nitTerceroDet": "1234567890",
                    "nombreTerceroDet": "ALEJANDRA LOPEZ LOPEZ",
                    "naturaleza": "C",
                    "crucePrefijo": "COM",
                    "cruceNumero": 3272,
                    "fechaVencimiento": null,
                    "valor": 67900.00000,
                    "baseImpuesto": 0.00000,
                    "cuota": 0,
                    "detalle": "SERV DE TRANSP INFORMAL",
                    "idSubcentroCosto": null,
                    "idCentroOperacion": 1,
                    "idProyecto": null,
                    "idActividad": null,
                    "idSucursal": null
                }
            ]
        }
    ]
}

{
    "success": true,
    "code": 204,
    "message": "No se encontraron registros",
}


Campos del resultado

Campo Tipo de Dato Descripción
id int Corresponde al id del registro contable
categoriaDocumento string Categoría del tipo de documento
prefijo string Prefijo del tipo de documento
numeroDoc Int Numero del documento contable
nitTerceroEnc string Numero de identificación del tercero del documento contable
nombreTerceroEnc string Nombre del tercero del documento contable
fechaDocumento string Fecha del documento contable
detalles Array[ObjetoDetalle]* Array de objetos de los detalles del documento contable


ObjetoDetalle:

Campo Tipo de Dato Descripción
cuenta Int Auxiliar o numero de cuenta contable del movimiento
nitTerceroDet string Numero de identificación del tercero del detalle
nombreTerceroDet string Nombre del tercero del detalle
naturaleza string Naturaleza del movimiento (C=Credito, D=Debito)
crucePrefijo string Prefijo del documento cruce
cruceNumero Int Numero del documento cruce
fechaVencimiento string Fecha de vencimiento del movimiento
valor decimal Valor del movimiento
baseImpuesto decimal Valor base de impuesto
cuota Int Numero de cuota, para documentos que manejan contabilización de cuotas
detalle string Comentarios del movimiento
idSubcentroCosto Int Id del subcentro de costo del movimiento
idCentroOperacion Int Id del centro de operacion del movimiento
idProyecto Int Id del proyecto del movimiento
idActividad Int Id de la actividad del movimiento
idSucursal Int Id de la sucursal del tercero del movimiento

</Tab>

<Tab name = "API Crear">

EndPoint: https://www.apis.serpi.com.co/api/v1/DocumentoContable Headers

Header Descripción
secretkey Secretkey proporcionada al cliente para consumos de las APIs

Authorization: 

Usar Bearer. Ejemplo “bearer {{token}}”.
{{token}} Token de autorizacion generado por SerpiERP

Body: 

[
    {
        "categoriaDocumento": "CCO",
        "prefijo": "COM",
        "numeroDoc": 2,
        "nitTerceroEnc": "123456789",
        "fechaDocumento": "2023-03-01",
        "detalles": [
            {
                "cuenta": 52954501,
                "nitTerceroDet": "123456789",
                "naturaleza": "D",
                "crucePrefijo": null,
                "cruceNumero": null,
                "fechaVencimiento": null,
                "valor": 67900.00000,
                "baseImpuesto": 0.00000,
                "cuota": 0,
                "detalle": "SERV DE TRANSP INFORMAL",
                "idSubcentroCosto": 4,
                "idCentroOperacion": 1,
                "idProyecto": null,
                "idActividad": null,
                "idSucursal": null
            },
            {
                "cuenta": 23359501,
                "nitTerceroDet": "123456789",
                "naturaleza": "C",
                "crucePrefijo": "COM",
                "cruceNumero": 1,
                "fechaVencimiento": null,
                "valor": 67900.00000,
                "baseImpuesto": 0.00000,
                "cuota": 0,
                "detalle": "SERV DE TRANSP INFORMAL",
                "idSubcentroCosto": null,
                "idCentroOperacion": 1,
                "idProyecto": null,
                "idActividad": null,
                "idSucursal": null
            }
        ]
    }
]

Campos resultado

Campo Tipo Requerido Descripción
categoriaDocumento string SI Categoría del tipo de documento
prefijo string SI Prefijo del tipo de documento
numeroDoc Int SI Numero del documento contable
nitTerceroEnc string SI Numero de identificación del tercero del documento contable
fechaDocumento string SI Fecha del documento contable
detalles Array[ObjetoDetalle]* SI Array de objetos de los detalles del documento contable


ObjetoDetalle:

Campo Tipo Requerido Descripción
cuenta Int SI Auxiliar o numero de cuenta contable del movimiento
nitTerceroDet string SI Numero de identificación del tercero del detalle
naturaleza string SI Naturaleza del movimiento (C=Credito, D=Debito)
crucePrefijo string NO Prefijo del documento cruce
cruceNumero Int NO Numero del documento cruce
fechaVencimiento string NO Fecha de vencimiento del movimiento
valor decimal SI Valor del movimiento
baseImpuesto decimal NO Valor base de impuesto
cuota Int NO Numero de cuota, para documentos que manejan contabilización de cuotas
detalle string NO Comentarios del movimiento
idSubcentroCosto Int NO Id del subcentro de costo del movimiento
idCentroOperacion Int NO Id del centro de operacion del movimiento
idProyecto Int NO Id del proyecto del movimiento
idActividad Int NO Id de la actividad del movimiento
idSucursal Int NO Id de la sucursal del tercero del movimiento


Authorization: 

Usar Bearer. Ejemplo “bearer {{token}}”.
{{token}} Token de autorizacion generado por SerpiERP

Response 

{
    "success": true,
    "code": 201,
    "errors": [],
    "message": "Se crearon 10 de 10 documentos contables"
}

</Tab>


<Tab name = "API Eliminar"> PUT/users

EndPoint: https://www.apis.serpi.com.co/api/v1/DocumentoContable Headers

Header Descripción
secretkey Secretkey proporcionada al cliente para consumos de las APIs

Authorization: 

Usar Bearer. Ejemplo “bearer {{token}}”.
{{token}} Token de autorizacion generado por SerpiERP

Body: 

{
    "idTipoDocumento": 6,
    "numeroDesde": 1,
    "numeroHasta": 10000,
    "fechaDesde": "2023-03-01",
    "fechaHasta": "2023-03-31"
}

Campos Solicitados

Campo Tipo Requerido Descripción
idTipoDocumento int SI Id del tipo de documento
numeroDesde int SI Numero inicial para filtrar por rango de números de documentos
numeroHasta int SI Numero final para filtrar por rango de números de documentos
fechaDesde string SI Fecha inicial para filtrar por rango de fecha del documento
fechaHasta bool SI Fecha final para filtrar por rango de fecha del documento



Authorization: 

Usar Bearer. Ejemplo “bearer {{token}}”.
{{token}} Token de autorizacion generado por SerpiERP

Response 

{
    "success": true,
    "code": 200,
    "errors": [],
    "message": "Se eliminaron 10 de 10 documentos contables "
}

</Tab>

</Tabs>

Códigos de estado HTTP

Código Descripción
200 La solicitud ha sido exitosa
201 La solicitud ha tenido éxito y ha llevado a la creación de un recurso
204 La solicitud se ha completado correctamente, pero no hay contenido para devolver en la respuesta
400 El servidor no puede o no procesará la petición debido a algo que es percibido como un error del cliente
401 La solicitud requiere autenticación, pero el cliente no ha proporcionado credenciales válidas o no está autorizado para acceder al recurso
403 El servidor ha entendido la solicitud, pero se niega a cumplirla debido a que el cliente no tiene permisos para acceder al recurso
404 El recurso solicitado no se ha encontrado en el servidor
500 Internal Server Error
503 El servidor no está disponible actualmente debido a una sobrecarga o mantenimiento temporal

¿Cómo consumir la API?

<Tabs>

<Tab name = "Java"> Request 

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://localhost:44305/api/v1/DocumentoContable")
  .method("GET", body)
  .addHeader("secretkey", "{{secret key}}")
  .addHeader("Authorization", "Bearer{{token}}")
  .build();
Response response = client.newCall(request).execute();

</Tab>

<Tab name = "C#"> Request 

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://localhost:44305/api/v1/DocumentoContable");
request.Headers.Add("secretkey", "{{secret key}}");
request.Headers.Add("Authorization", "Bearer{{token}}");
var content = new StringContent("", null, "text/plain");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

</Tab>

<Tab name = "PHP"> Request 

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://localhost:44305/api/v1/DocumentoContable');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'secretkey' => '{{secret key}}',
  'Authorization' => 'Bearer {{token}}'
));
$request->setBody('');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

</Tab>

</Tabs>

Obtenido de «https://www.wikiserpi.com/index.php?title=API_Documentos_Contables&oldid=916»