Descripción general

Endpoint /contacts

Los contactos en Alegra representan los clientes y proveedores a los cuales asocias facturas de venta, notas crédito, facturas de compra y demás movimientos. Para saber más sobre los contactos haz clic aquí.

Un contacto se puede clasificar en cliente, proveedor, los dos o ninguno. Esta clasificación es únicamente informativa, la aplicación permite asociar facturas de venta a contactos de cualquier tipo.

Un contacto contiene los siguientes atributos:

Nombre

Tipo

Descripción

Ejemplo

id

Integer

Identificador único que representa un contacto específico. La aplicación lo asigna automáticamente.

5

name

String

Nombre del contacto.

Juan Pablo Mesa

identification

String

Número de identificación del contacto. Ejemplos: cédula, RFC, RNC, número de pasaporte.

901.589.545-2

identification (Perú)

Object

Solo para versión Alegra Perú.

Objeto identification que indica la identificación del contacto.

Contiene los siguientes atributos:

  • type: India el tipo de identificación, se debe enviar el id correspondiente al tipo de identificación. Consulta el catálogo de parámetros correspondiente a cada país haciendo clic aquí.

  • number: Indica el número de identificación.

{
"identification": {
"type": "RUC",
"number": 12345678911
}
}

identificationObject

Object

Solo para versión Alegra Costa Rica, Alegra Colombia y Alegra Rep. Dominicana.

Objeto que indica la identificación del contacto.

Contiene los siguientes atributos:

  • type: India el tipo de identificación, se debe enviar el id correspondiente al tipo de identificación. Consulta el catálogo de parámetros correspondiente a cada país haciendo clic aquí.

  • number: Indica el número de identificación.

Solo para Alegra Colombia

  • dv: Indica el dígito de verificación de identificación, se hace visible únicamente cuando el tipo de identificación es NIT. El dígito de verificación se calcula automaticamente a partir de la identificación.

{
"identification": {
"type": "CC",
"number": "111111111"
}
}

identificationObject

Object

Solo para Alegra Panamá
Objeto que indica la identificación del contacto.

Contiene los siguientes atributos:

  • kindOfPerson: indica el tipo de persona, puede ser natural (PERSON_ENTITY) o jurídica (LEGAL_ENTITY).
  • number: RUC de la compañía.
  • dv: Dígito verificador.

{
"identificationObject": {
"kindOfPerson": "LEGAL_ENTITY",
"number": "11111-1-25646",
"dv": "08"
}
}

email

String

Correo electrónico del contacto.

[email protected]

phonePrimary

String

Número telefónico principal del contacto.

+(99)(999) 999-99-99

phoneSecondary

String

Número telefónico secundario del contacto.

(999) 999-99-99

fax

String

Fax del contacto.

(999) 999-99-99

mobile

String

Número de célular/móvil.

333 33 33

observations

String

Observaciones del contacto.

priceList

Object

Objecto PriceList que indica la lista de precios asociada al contacto. Contiene los siguientes atributos:

  • id: Identificador de la lista de precios.
  • name: Nombre de la lista de precios.

{
"id" : 5,
"name": "Distribuidor"
}

seller

Object

Objeto Seller que indica el vendedor asociado al contacto.
Contiene los siguientes atributos:

  • id: Identificador del vendedor.
  • name : Nombre del vendedor.
  • identification: Identificación (Nit, RFC, cédula, etc) del vendedor.
  • observations : Observaciones del vendedor.

{
"id" : "12",
"name" : "Diana Giraldo",
"identification" : "12355598",
"observations" : "Vendedor del área del oriente"
}

term

Object

Objecto Term que indica el término de pago del contacto, los cuales son los parámetros que definen cómo es el vencimiento de tus facturas de venta.
Contienen los siguientes atributos:

  • id: Identificador interno del término de pago.
  • name: Nombre del término de pago. Ej: 8 días
  • days: Días del término de pago. Ej: Para contactos que tienen 8 días de plazo para pagar, este atributo se configura en 8.

{
"id" : 1,
"name" : "8 días",
"days" : 8
}

address

Object

Objeto que contiene la información de la dirección del contacto.

Contiene los siguientes atributos:

  • address : Indica la dirección del contacto.
  • city: Ciudad del contacto.

{
"address" : "Calle principal #45",
"city" : "Barcelona"
}

address (México)

Object

Solo para versión Alegra México.

Objeto que contiene la información de la dirección del contacto.

Contiene los siguientes atributos:
street: Indica la calle del contacto.
exteriorNumber: Indica el número de exterior.
interiorNumber: Indica el número de interior.
colony: Indica la colonia del contacto.
country: Indica el país del contacto. Si con el contacto se desea timbrar documentos se debe especificar el codigo de pais de 3 digitos de acuerdo a la ISO 3166-1 alpha-3 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).
locality: Indica la localidad.
municipality: Indica el municipio.
state : Indica el estado del contacto.
*zipCode: Indica el código postal del contacto.

{
"street" : "Avenida Primero de Mayo",
"exteriorNumber" : 95,
"interiorNumber" : "1B",
"colony" : "Benito Juaréz",
"country" : "México",
"locality" : "",
"municipality" : "",
"state" : "D.F",
"zipCode" : "12345"
}

address (Perú)

Object

Solo para versión Alegra Perú.

Objeto que contiene la información de la dirección del contacto.

Contiene los siguientes atributos:

address: Indica la dirección del contacto.
state: Indica el departamento del contacto.
city: Indica la provincial del contacto.
district: Indica el distrito del contacto.
urbanization: Indica la urbanización del contacto.
ubigeoCode: Indica el código ubigeo.

{
"address": "AV SAN MARTIN 101",
"state": "LORETO",
"city": "MARISCAL RAMON CASTILLA",
"district": "YAVARI",
"urbanization": "SAN RAFAEL",
"ubigeoCode": 150603
}

address (Costa rica)

Object

Solo para versión Alegra Costa Rica.

Objeto que contiene la información de la dirección del contacto.

Contiene los siguientes atributos:

  • address: Indica otras señas de la ubicación.
  • department: Indica el nombre de la provincia.
  • city: Indica el nombre del cantón. (El cantón debe pertenecer a la provincia)
  • district: Indica el nombre del distrito. (El distrito debe pertenecer al cantón)
  • neighborhood: Indica el nombre del barrio. (El barrio debe pertenecer al distrito)

{
"address" : "Calle 3",
"department" : "Limón",
"city" : "Pococí",
"district" : "Colorado",
"neighborhood" : "Verdades"
}

address (Colombia)

Object

Solo para versión Alegra Colombia.

Objeto que contiene la información de la dirección del contacto.

Contiene los siguientes atributos:

  • address: Indica la dirección del contacto.
  • department: Indica el nombre del departamento del contacto.
  • city: Indica el nombre de la ciudad del contacto.
  • country: Indica el país del contacto.

{
"address" : "Calle 20",
"department" : "Cundinamarca",
"city" : "Zipaquirá",
"country": "Colombia"
}

address (Argentina)

Object

Solo para versión Alegra Argentina.

Objeto que contiene la información de la dirección del contacto.

Contiene los siguientes atributos:

  • province: Indica el nombre de la provincia del contacto.
  • city: Indica el nombre de la ciudad del contacto.
  • address: Indica la dirección del contacto.
  • postalCode: Indica el código postal del contacto.

"address": {
"province": "Ciudad
Autónoma de Buenos
Aires",
"city": "Ciudad autónoma
de buenos aires",
"address": "Avenida 38 -
65",
"postalCode": "12313"
}

address (Chile)

Object

Solo para versión Alegra Chile.

Objeto que contiene la información de la dirección del contacto.

Contiene los siguientes atributos:

  • city: Indica el nombre de la ciudad.
  • region: Indica el nombre de la región.
  • commune: Indica el nombre de la comuna. (La comuna debe pertenecer a la región).
  • description: Indica otras señas de la ubicación.

{
"city": "Santiago",
"region": "Metropolitana",
"commune": "Santiago",
"description": "Av. Grecia 1853-1951"
}

address (Panamá)

Object

Solo para versión Alegra Panamá.

Objeto que contiene la información de la dirección del contacto.

Contiene los siguientes atributos:

  • province: Indica el nombre de la provincia.
  • district: Indica el nombre del distrito.
  • township: Indica el nombre del corregimiento.
  • address: Indica la dirección del contacto

Para facturación electrónica, si el tipo de receptor es extranjero se debe envíar solo el address y el country.

"address": {
"province": "Bocas del toro",
"district": "Bocas del toro",
"township": "Bastimentos",
"address": "Av. Siempre viva"
}

Para extranjero:
"address": {
"country": "Argentina",
"address": "Av. Siempre viva"
}

address (Rep. Dominicana)

Object

Solo para versión Alegra Rep. Dominicana.

Objeto que contiene la información de la dirección del contacto.

Contiene los siguientes atributos:

  • province: Indica el nombre de la provincia.
  • municipality: Indica el nombre de la municipalidad.
  • description: Indica la dirección del contacto

type

Array

Indica si el contacto es cliente, proveedor, los dos o ninguno. Las opciones posibles son 'client' si el contacto es cliente, 'provider' si el contacto es proveedor.

['provider','client']

internalContacts

Array

Array de objetos internalContact que indica los contactos internos asociados al contacto. Cada objeto contiene los siguientes atributos:

  • id: Identificador interno del contacto interno.
  • name: Nombre del contacto interno.
  • lastName: Apellido del contacto interno.
  • email: Correo del contacto interno.
  • phone: Teléfono del contacto interno.
  • mobile: Célular/móvil del contacto interno.
  • sendNotifications: Indica si se desee activar las notificaciones de vencimiento de factura. Ver más.

{
"id" : 1,
"name" : "Andrea",
"lastName" : "Restrepo",
"email" : "[email protected]",
"phone" : "999-99-99 ext 105"
"mobile" : "",
"sendNotifications" : true
}

cfdiUse (México)

String

Solo para versión Alegra México.
Indica la clave del Uso CFDI asociada al contacto.

G01

kindOfPerson (Colombia)

String

Solo para versión Alegra Colombia.

Indica el tipo de persona, se debe enviar el id correspondiente al tipo de persona.
Consulta el catálogo de parámetros correspondiente a cada país haciendo clic aquí.

LEGAL_ENTITY

regime (Colombia)

String

Solo para versión Alegra Colombia.

Indica el régimen al que pertenece el contacto, se debe enviar el id correspondiente al régimen.
Consulta el catálogo de parámetros correspondiente a cada país haciendo clic aquí.

Si no se envía ningún valor en este atributo, el régimen se asigna automaticamente, a partir del tipo de identificación. únicamente se asigna régimen común para NIT, en otros casos será régimen simplificado.

COMMON_REGIME

paymentMethod (México)

String

Solo para versión Alegra México.

Indica el método de pago del contacto. Las opciones posibles son: cash Efectivo, debit-card Tarjeta débito, credit-card Tarjeta de crédito, service-card Tarjeta de servicio, transfer Transferencia electónica, check Cheque nominativo, electronic-wallet Monedero electrónico, electronic-money Dinero electrónico, grocery-voucher Vale de despensa, other Otros. Se debe ingresar en minúscula.

credit-card

paymentType (México)

String

Solo para versión Alegra México.

Para México, representa el método de la factura. Admite los valores PUE para Pago en Una sola Exhibición y PPD para Pago en Parcialidades o Diferido. Se debe ingresar en mayúscula.

PUE

ivaCondition (Argentina)

String

Solo para versión Alegra Argentina.

Para Argentina, se debe especificar como atributo obligatorio la condición de IVA del contacto.

IVA_RESPONSABLE_NO_INSCRIPT

giro (Chile)

String

Solo para versión Alegra Chile

Giro del contacto, este campo es obligatorio si se quiere emitir documentos para facturación electrónica.

Giro de negocio

identification (Chile)

String

Solo para versión Alegra Chile

Para Chile, este campo es obligatorio si se quiere emitir documentos para facturación electrónica, el formato debe ser el mismo que los documentos RUT en Chile, es decir, de 6 a 8 dígitos, un guion ("-") y otro dígito o una K así (6666666-K).

operationType (México)

String

Solo para versión Alegra México

Este campo indica el tipo de operación al que se somete el contacto, bien sea para servicios profesionales, arrendamiento de propiedades u otros.

PROFESSIONAL_SERVICES

thirdType (México)

String

Solo para versión Alegra México

Este campo indica el tipo de tercero al que pertenece el contacto, bien sea para nacionales o extranjeros.

NATIONAL

thirdType (Panamá)

String

Solo para versión Alegra Panamá

Este campo indica el tipo de receptor al que pertenece el contacto. Los valores posibles son:

  • Consumidor Final (FINAL_CONSUMER).
  • Contribuyente (TAXPAYER).
  • Gobierno (GOVERNMENT).
  • Extranjero (FOREIGN).

FINAL_CONSUMER

fiscalId

String

Solo para versión Alegra México

Indica el ID fiscal del contacto cuando el tipo de tercero del proveedor es extranjero.

fiscalResponsabilities (Colombia)

Array

Solo para versión Alegra Colombia.
Objeto que contiene la información de las responsabilidades fiscales de la compañía, cuando la facturación electrónica está activa.

Consulta el catálogo de parámetros correspondiente a cada país haciendo clic aquí.

settings

Object

Solo para las versiones de Alegra Perú, Argentina, Costa Rica y Colombia

Objeto que representa ciertas configuraciones del contacto.

Contiene los siguientes atributos:

  • sendElectronicDocuments (bool): Indica si se desean enviar automáticamente los documentos electrónicos por correo, luego de que hayan sido aceptados por la entidad reguladora de cada país.
{
  "sendElectronicDocuments": true
}

accounting

Object

Objeto que representa las cuentas por cobrar y pagar asociadas a un contacto.

accountReceivable: Cuenta por cobrar.

debtToPay: Cuenta por pagar

"accounting": {
  "accountReceivable": {
    "id": "5114",
    "idParent": "5007",
    "name": "Clientes extranjeros",
    "description": "",
    "type": "asset",
    "code": null,
    "readOnly": false,
    "categoryRule": {
      "id": "136",
      "name": "Clientes extranjeros",
      "key": "FOREIGN_RECEIVABLE_ACCOUNTS_MEX"
    },
    "metadata": {
      "satGroupingCode": "",
      "satGroupingText": ""
    }
  },
  "debtToPay": {
    "id": "5116",
    "idParent": "5034",
    "name": "Proveedores extranjeros",
    "description": "",
    "type": "liability",
    "code": null,
    "readOnly": false,
    "categoryRule": {
      "id": "138",
      "name": "Proveedores extranjeros",
      "key": "FOREIGN_DEBTS_TO_PAY_PROVIDERS_MEX"
    },
    "metadata": {
      "satGroupingCode": "",
      "satGroupingText": ""
    }
  }
}

exoneration

Array

Solo para versión Alegra Costa Rica
Arreglos que contiene objetos con la información de exoneración asociada al contacto, usada para facturación electrónica.

Los atributos de cada objeto de exoneración son:

  • documentType: Indica el tipo de documento de exoneración.
  • documentNumber: Indica el número de exoneración.
  • institutionName: Indica el nombre de la institución.
  • emissionDate: Indica la fecha de emisión (d/m/Y).
  • dueDate: Indica la fecha de vencimiento (no obligatorio).
  • percentage: Indica el porcentaje de exoneración.

Consulta el catálogo de parámetros correspondiente a cada país haciendo clic aquí.

"exoneration": [
    {
    "documentType": "EXEMPTIONS_DGH",
    "documentNumber": "A-00256928-19",
    "institutionName": "Dirección General de Hacienda",
    "emissionDate": "02/07/2020",
     "dueDate": "02/07/2021",
     "percentage": "9"
    }
]

defaultInvoiceResolution (Rep. Dominicana)

integer

Representa el ID de una numeración con documentType invoice la cual será usada por defecto a la hora de facturar con el contacto específico.