{ "openapi": "3.1.0", "info": { "title": "Taxo Facturación México: Partners API", "version": "1.0.0", "description": "Gestiona las cuentas de tus clientes de facturación en México: planes, clientes, suscripciones y folios. Obtén un token con `POST /v1/auth/token` y envíalo en la cabecera `Authorization: Bearer `. Producción y sandbox comparten la URL base: para ejecutar una petición en sandbox agrega la cabecera `F-Sandbox-Mode: true`." }, "servers": [ { "url": "https://invoice.taxo.ws/mx/partners", "description": "Producción y sandbox (cabecera F-Sandbox-Mode)" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Token de acceso obtenido en `POST /v1/auth/token` con tus credenciales de cliente." } }, "schemas": { "Error": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "code": { "type": "string" } } }, "ValidationError": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "code": { "type": "string" } } }, "Product": { "type": "object", "properties": { "uuid": { "type": "string" }, "name": { "type": "string" }, "services": { "type": "object" }, "sales": { "type": "integer" }, "expiration_type": { "type": "integer" }, "status": { "type": "string" }, "vigencies": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "folios": { "type": "integer" }, "price": { "type": "string" }, "expiration_period": { "type": "string" } } } }, "pdf_templates": { "type": "array", "items": { "type": "string" } } } }, "ProductInput": { "type": "object", "required": [ "name", "vigencies", "services" ], "properties": { "name": { "type": "string", "example": "Plan especial" }, "vigencies": { "type": "array", "items": { "type": "object", "properties": { "folios": { "type": "integer" }, "vigency": { "type": "string", "enum": [ "Mensual", "Trimestral", "Semestral", "Anual", "SP" ], "description": "Periodo de validez del plan. \"SP\" corresponde a sin periodicidad." }, "price": { "type": "number" } } } }, "services": { "type": "object", "properties": { "api": { "type": "boolean" }, "smtp_mail": { "type": "boolean" }, "custom_email": { "type": "boolean" }, "pdf_templates": { "type": "array", "items": { "type": "string" } }, "invoices_migrator": { "type": "boolean" }, "auto_invoice": { "type": "boolean" }, "extra_rfc": { "type": "integer" }, "extra_user": { "type": "integer" } } } } }, "Pagination": { "type": "object", "properties": { "currentPage": { "type": "integer" }, "lastPage": { "type": "integer" }, "perPage": { "type": "integer" }, "total": { "type": "integer" } } }, "Subscription": { "type": "object", "properties": { "uuid": { "type": "string" }, "name": { "type": "string" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "folios": { "type": "integer" }, "status": { "type": "string" }, "client": { "type": "object", "properties": { "uuid": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "status": { "type": "string" } } }, "product": { "type": "object", "properties": { "uuid": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" } } }, "vigency": { "type": "string" }, "folios_used": { "type": "integer" } } } } }, "paths": { "/v1/auth/token": { "post": { "tags": [ "Autenticación" ], "summary": "Obtener token de acceso", "description": "Genera un token Bearer mediante el flujo Client Credentials de OAuth2.", "security": [], "parameters": [ { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Activar modo sandbox" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "example": "client_credentials" }, "client_id": { "type": "string", "example": "YOUR_CLIENT_ID" }, "client_secret": { "type": "string", "example": "YOUR_CLIENT_SECRET" } } } } } }, "responses": { "200": { "description": "Token generado correctamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "example": 31535999 }, "access_token": { "type": "string" } } } } } }, "401": { "description": "Credenciales inválidas", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } } } } }, "/v1/products": { "get": { "tags": [ "Planes" ], "summary": "Consultar planes", "description": "Obtiene un listado paginado de todos los planes configurados.", "parameters": [ { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } }, { "in": "query", "name": "page", "schema": { "type": "integer" } }, { "in": "query", "name": "search", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listado de planes", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "description": "No autenticado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Planes" ], "summary": "Crear plan", "description": "Registra un nuevo plan en el catálogo.", "parameters": [ { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } } }, "responses": { "200": { "description": "Plan creado", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string" }, "data": { "$ref": "#/components/schemas/Product" } } } } } }, "422": { "description": "Error de validación", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } }, "delete": { "tags": [ "Planes" ], "summary": "Borrar planes", "description": "Elimina uno o múltiples planes por sus UUIDs.", "parameters": [ { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "items": { "type": "string" }, "example": [ "a1e2019fe2b542af96caf6f9320781bd" ] } } } } } }, "responses": { "200": { "description": "Planes eliminados", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Plan no encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/products/{uuid}": { "get": { "tags": [ "Planes" ], "summary": "Mostrar plan", "description": "Obtiene los detalles de un plan específico por UUID.", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detalle del plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string" }, "data": { "$ref": "#/components/schemas/Product" } } } } } }, "404": { "description": "Plan no encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Planes" ], "summary": "Actualizar plan", "description": "Modifica la configuración de un plan existente.", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } } }, "responses": { "200": { "description": "Plan actualizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string" }, "data": { "$ref": "#/components/schemas/Product" } } } } } }, "404": { "description": "Plan no encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/products/{uuid}/change-status": { "post": { "tags": [ "Planes" ], "summary": "Cambiar estatus de plan", "description": "Activa o desactiva un plan específico por UUID.", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Estatus actualizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string" }, "data": { "$ref": "#/components/schemas/Product" } } } } } }, "404": { "description": "Plan no encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/clients": { "get": { "tags": [ "Clientes" ], "summary": "Consultar clientes", "description": "Obtiene un listado de todos los clientes registrados.", "parameters": [ { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listado de clientes", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "No autenticado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Clientes" ], "summary": "Crear cliente", "description": "Registra una nueva cuenta de cliente y le asigna un plan.", "parameters": [ { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client", "tax_information", "product" ], "properties": { "client": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "example": "MARTIN LOPEZ" }, "email": { "type": "string", "example": "ejemplo@ejemplo.com" } } }, "tax_information": { "type": "object", "required": [ "tax_id", "legal_name", "postal_code", "invoice_use_key", "tax_regime" ], "properties": { "tax_id": { "type": "string", "example": "FUNK671228PH1" }, "legal_name": { "type": "string" }, "postal_code": { "type": "string" }, "invoice_use_key": { "type": "string", "example": "G01" }, "tax_regime": { "type": "string", "example": "601" } } }, "product": { "type": "object", "required": [ "uuid", "vigency_uuid" ], "properties": { "uuid": { "type": "string" }, "vigency_uuid": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Cliente creado", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Error de validación", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/v1/clients/{uuid}": { "patch": { "tags": [ "Clientes" ], "summary": "Actualizar cliente", "description": "Modifica los datos generales y fiscales de un cliente existente.", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } } }, "tax_information": { "type": "object", "properties": { "tax_id": { "type": "string" }, "legal_name": { "type": "string" }, "postal_code": { "type": "string" }, "invoice_use_key": { "type": "string" }, "tax_regime": { "type": "string" }, "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "neighborhood": { "type": "string" }, "address": { "type": "string" }, "additional_email": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Cliente actualizado", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Cliente no encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/clients/suspend": { "post": { "tags": [ "Clientes" ], "summary": "Suspender cliente", "description": "Suspende uno o múltiples clientes por sus UUIDs.", "parameters": [ { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string", "description": "Mensaje que recibirá el cliente" }, "keep_folios": { "type": "boolean", "description": "Si los folios disponibles deben conservarse" } } } } } }, "responses": { "200": { "description": "Clientes suspendidos", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Cliente no encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/clients/reactivate": { "post": { "tags": [ "Clientes" ], "summary": "Reactivar cliente", "description": "Reactiva uno o múltiples clientes previamente suspendidos.", "parameters": [ { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Clientes reactivados", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Cliente no encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/clients/{uuid}/resend-credentials": { "post": { "tags": [ "Clientes" ], "summary": "Reenviar accesos al cliente", "description": "Reenvía por correo los accesos de una cuenta previamente creada.", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accesos reenviados correctamente", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Cliente no encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/subscriptions": { "get": { "tags": [ "Suscripciones" ], "summary": "Consultar suscripciones", "description": "Obtiene el listado de todas las suscripciones de tus clientes.", "parameters": [ { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listado de suscripciones", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "No autenticado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/subscriptions/{uuid}": { "get": { "tags": [ "Suscripciones" ], "summary": "Mostrar suscripción", "description": "Obtiene los detalles de una suscripción específica por UUID.", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detalle de la suscripción", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string" }, "data": { "$ref": "#/components/schemas/Subscription" } } } } } }, "404": { "description": "Suscripción no encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/subscriptions/{uuid}/renew": { "post": { "tags": [ "Suscripciones" ], "summary": "Renovar suscripción", "description": "Extiende la vigencia de una suscripción con el plan indicado.", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_uuid", "vigency_uuid" ], "properties": { "product_uuid": { "type": "string" }, "vigency_uuid": { "type": "string" } } } } } }, "responses": { "200": { "description": "Suscripción renovada", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string" }, "data": { "$ref": "#/components/schemas/Subscription" } } } } } }, "422": { "description": "Error de validación", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/v1/subscriptions/{uuid}/add-folios": { "post": { "tags": [ "Suscripciones" ], "summary": "Agregar folios", "description": "Agrega una cantidad de folios a la suscripción indicada.", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "folios", "amount" ], "properties": { "folios": { "type": "integer", "example": 5 }, "amount": { "type": "number", "format": "float", "example": 2.99 } } } } } }, "responses": { "200": { "description": "Folios agregados correctamente", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Error de validación", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/v1/subscriptions/{uuid}/remove-folios": { "post": { "tags": [ "Suscripciones" ], "summary": "Retirar folios", "description": "Retira una cantidad de folios de la suscripción indicada.", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "folios" ], "properties": { "folios": { "type": "integer", "example": 4 } } } } } }, "responses": { "200": { "description": "Folios retirados correctamente", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Error de validación", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/v1/subscriptions/suspend": { "post": { "tags": [ "Suscripciones" ], "summary": "Suspender suscripción", "description": "Suspende una o múltiples suscripciones activas.", "parameters": [ { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "keep_folios": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Suscripciones suspendidas", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Suscripción no encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/subscriptions/reactivate": { "post": { "tags": [ "Suscripciones" ], "summary": "Reactivar suscripción", "description": "Reactiva una o múltiples suscripciones previamente suspendidas.", "parameters": [ { "in": "header", "name": "F-Sandbox-Mode", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Suscripciones reactivadas", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Suscripción no encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }