Guía Técnica de Integración

Esta documentación proporciona la información necesaria para consumir la API de Proveedores GEC de forma correcta, eficiente y segura.

Endpoints

Autenticación

Todas las rutas funcionales bajo /api requieren la cabecera x-emp-api-key.

x-emp-api-key: API_KEY_PROPORCIONADA

Formato de error estándar

Códigos comunes: 400, 401 y 500.

{
  "success": false,
  "code": "REQUEST_VALIDATION_FAILED",
  "message": "Request validation failed",
  "details": [
    {
      "path": "/query/IdProv",
      "message": "must be integer",
      "location": "query"
    }
  ]
}

GET /api/proveedores

Consulta proveedores por filtros opcionales de búsqueda.

Tipo de contenido

application/json

Campos y validaciones

GET /api/proveedores?IdProv=15&Rfc=PAP181818AA12&ActividadSAT=1&ActividadSAT=15
Content-Type: application/json
x-emp-api-key: API_KEY_PROPORCIONADA

Ejemplo de respuesta

Ejemplo de respuesta

[
  {
    "IdProv": "15",
    "Rfc": "PAP181818AA12",
    "NombreComercial": "J PEREZ SOLUCIONES",
    "DenomRazonSocial": "JUAN PEREZ GOMEZ",
    "Dat_ASat": [
      {
        "IdClave": 1,
        "Actividad": "Agricultura"
      },
      {
        "IdClave": 2,  
        "Actividad": "Ganadería"
      }
    ]
  }
]

POST /api/proveedores

Este endpoint permite registrar un nuevo proveedor.

Es posible Enviar la información de dos formas:

1. application/json: cuando solo se desea registrar los datos del proveedor.
2. multipart/form-data: cuando de desea adjuntar documentos junto con los datos.

Para adjuntar documentos, primero consulta el catálogo disponible en el endpoint /api/documentos. Ahí encontrarás los identificadores necesarios para cada documento, el nombre correspondiente al campo IdDoc del catálogo es el nombre del parametro en este método

Flujo recomendado para el registro de proveedores:

1. Utilizar el endpoint /api/proveedores por filtro de RFC para verificar que el proveedor a registrar no exista.
2. Consultar el catálogo de documentos requeridos en el endpoint /api/documentos.
3. Si se usará multipart/form-data, enviar los documentos requeridos como parámetros de tipo archivo con el nombre correspondiente al campo IdDoc del catálogo.
4. Utilizar este método para registrar el nuevo proveedor.
5. Validar el codigo http de la respuesta. 201 indica que el proveedor se registró correctamente; 202 indica que el proveedor fue registrado pero sus documentos no fueron adjuntados correctamente, y solo aplica cuando se usó multipart/form-data. En ese caso, se debe hacer uso de api/proveedores/:IdProv/documentos para intentar adjuntar los documentos nuevamente.
6. En caso de recibir un código http diferente a 201 o 202, revisar el mensaje de error para identificar la causa y resolverla antes de intentar registrar el proveedor nuevamente.

Tipo de contenido

application/json y multipart/form-data

Campos y validaciones

Documentos

1. Consultar el catálogo de documentos requeridos en el endpoint /api/documentos
2. Adjuntar documentos según el tipo de persona. Cada IdDoc del catálogo corresponde al nombre del campo para el archivo en el formulario. Por ejemplo, si el IdDoc es "1", el campo para el archivo debe llamarse "1".

Ejemplo de request (solo datos)

POST /api/proveedores
      Content-Type: application/json
      x-emp-api-key: API_KEY_PROPORCIONADA

      {
        "Persona": "F",
        "Genero": "O",
        "DenominacionRazonSocial": "JUAN PEREZ GOMEZ",
        "Rfc": "PAP181818AA12",
        "NombreComercial": "J PEREZ SOLUCIONES",
        "CURP": "QCMPAVTAGI6LA06CLM",
        "Calle": "Calle Principal",
        "NoExterior": "123",
        "NoInterior": "A",
        "Colonia": "Centro",
        "Localidad": "Colima",
        "Municipio": "Colima",
        "Estado": "Colima",
        "Pais": "Mexico",
        "CodigoPostal": "28000",
        "ActividadesSAT": ["1", "15"],
        "ServiciosProductos": "Asesoria en tecnologia",
        "Telefono": "3331234567",
        "PersonaContacto": "Maria Lopez",
        "CelularContacto": "3121234567",
        "CorreoElectronico": "contacto@empresa.com"
      }

Ejemplo de request (con documentos)

POST /api/proveedores
      Content-Type: multipart/form-data
      x-emp-api-key: API_KEY_PROPORCIONADA

      Body (form-data):
      - Persona
      - Genero (si Persona = F)
      - DenominacionRazonSocial
      - Rfc
      - NombreComercial
      - CURP (si Persona = F)
      - Calle
      - NoExterior
      - NoInterior
      - Colonia
      - Localidad
      - Municipio
      - Estado
      - Pais
      - CodigoPostal
      - ActividadesSAT
      - ServiciosProductos
      - Telefono
      - PersonaContacto
      - CelularContacto
      - RepresentanteLegal (si Persona = M)
      - CorreoElectronico
      - 1 (archivo) ejemplo, el nombre final lo determina el IdDoc del catálogo de documentos
      - 2 (archivo) ejemplo, el nombre final lo determina el IdDoc del catálogo de documentos
      - 3 (archivo) ejemplo, el nombre final lo determina el IdDoc del catálogo de documentos
      - 4 (archivo) ejemplo, el nombre final lo determina el IdDoc del catálogo de documentos
      - 5 (archivo) ejemplo, el nombre final lo determina el IdDoc del catálogo de documentos
      

Ejemplo de respuesta

{
  "IdProv": "10",
  "DenomRazonSocial": "",
  "Rfc": "PAP181818AA",
  "Code": "1",
  "Mensaje": "Proveedor creado exitosamente"
}

PATCH /api/proveedores/:IdProv/documentos

Actualiza los documentos de un proveedor registrado usando el RFC en el cuerpo y archivos adjuntos identificados por el IdDoc correspondiente.

Tipo de contenido

multipart/form-data

Campos y validaciones

Ejemplo de request

PATCH /api/proveedores/123/documentos
Content-Type: multipart/form-data
x-emp-api-key: API_KEY_PROPORCIONADA

Body (form-data):
- Rfc
- 1 (archivo PDF)
- 2 (archivo PDF)
- 3 (archivo PDF)

Ejemplo de respuesta

{
  "IdProv": "123",
  "DenomRazonSocial": "PROVEEDOR DEMO SA DE CV",
  "Rfc": "PDM181818AA12",
  "Code": "1",
  "Mensaje": "Documentos de proveedor actualizados exitosamente"
}

GET /api/actividades-sat

Retorna catálogo de actividades SAT.

Tipo de contenido

application/json

Campos y validaciones

Ejemplo de request

GET /api/actividades-sat
      Content-Type: application/json
      x-emp-api-key: API_KEY_PROPORCIONADA

Ejemplo de respuesta

[
  {
    "IdClave": 1,
    "Actividad": "Agricultura"
  },
  {
    "IdClave": 2,
    "Actividad": "Ganadería"
  }
]

GET /api/documentos

Retorna catálogo de documentos. Si no se envía tipoPersona, devuelve todos.

Tipo de contenido

application/json

Campos y validaciones

Ejemplo de request

GET /api/documentos?tipoPersona=F
      Content-Type: application/json
      x-emp-api-key: API_KEY_PROPORCIONADA

Ejemplo de respuesta

[
  {
    "IdDoc": "1",
    "Documento": "IDENTIFICACION OFICIAL",
    "AplicaPara": "FISICA/MORAL",
    "EsRequerido": "SI"
  },
  {
    "IdDoc": "4",
    "Documento": "ACTA CONSTITUTIVA",
    "AplicaPara": "MORAL",
    "EsRequerido": "SI"
  }
]

GET /healthcheck

Verificación operativa del servicio.

Tipo de contenido

application/json

Campos y validaciones

Ejemplo de request

GET /healthcheck
      Content-Type: application/json

Ejemplo de respuesta

{
  "status": "UP",
  "service": "api-proveedores-gec",
  "build": "1.2.0"
}