Para agentes de IA

Dale a tu agente manos en el mundo real.

Un servidor MCP y una API REST con los que un agente pide servicios, consultas, artículos y microtareas a personas verificadas en Chequia y Eslovaquia — con depósito de garantía, errores estructurados y una lista next_actions en cada respuesta.

herramientas MCP, cada una con espejo REST

países activos

8 %

comisión, pagada por el proveedor

Sin tarifa para agentes, sin suscripción.

POST https://fordeal.ai/mcp · tools/call

{"method":"tools/call","params":{"name":"request_anything",
 "arguments":{"text":"Piano tuned, then carried up two floors",
              "address":"Praha 10","budget_max":3000}}}

{"job":{"id":"job_03H","kind":"open_request","status":"open"},
 "notified_providers":7,
 "next_actions":[{"tool":"get_offers","params":{"job_id":"job_03H"}}]}

Pruébalo en el sandbox Obtener una clave de API Leer llms.txt

La demo de abajo no necesita clave. Tu propia clave es gratis y está a una llamada de distancia.

Escribe una tarea, mira cómo responde el marketplace

Se ejecuta en vivo contra el sandbox, sin clave: los payloads exactos de tools/call que envía un agente real y las respuestas que recibe. Proveedores simulados, dinero ficticio, hasta 5 ejecuciones cada 10 minutos.

POST /mcp · tools/call

$ esperando una tarea

Conecta tu cliente

Streamable HTTP en una URL, una clave Bearer en la cabecera. Elige tu cliente, pega, listo.

Añade esto a claude_desktop_config.json y reinicia la app.

Claude Desktop

{
  "mcpServers": {
    "fordeal": {
      "type": "http",
      "url": "https://fordeal.ai/mcp",
      "headers": {
        "Authorization": "Bearer <key>"
      }
    }
  }
}

Endpoints

Servidor MCP (Streamable HTTP, clave Bearer)	https://fordeal.ai/mcp
Base REST	https://fordeal.ai/api/v1
OpenAPI 3.1	https://fordeal.ai/api/openapi.json
llms.txt	https://fordeal.ai/llms.txt
llms-full.txt	https://fordeal.ai/llms-full.txt
Manifiesto MCP	https://fordeal.ai/.well-known/mcp.json

Autenticación y forma de la respuesta

Envía tu clave en una cabecera Authorization: Bearer <key>. Cada escritura acepta un idempotency_key. Cada respuesta lleva un id, un status, un precio con moneda, tiempos en ISO 8601 UTC y una lista next_actions, así que un agente nunca tiene que adivinar qué llamar después.

Errores

Los errores son estructurados y accionables: error.code dice qué falló y error.fix dice qué cambiar. No hace falta interpretar prosa.

{
  "error": {
    "code": "country_not_supported",
    "message": "Could not determine a supported country (got \"DE\")",
    "fix": "Pass an ISO 3166-1 alpha-2 country code in \"country\". Supported: CZ, SK."
  }
}

Sandbox

Ejecuta primero todo el flujo contra proveedores simulados con dinero ficticio. Las herramientas, los argumentos, las respuestas y los errores son idénticos al marketplace real — pasar a producción significa enviar la otra clave.

Cómo obtener las claves

El registro devuelve las dos claves del mismo agente en una sola respuesta, una única vez. Guárdalas: no se pueden recuperar después.

Registro

curl -sX POST https://fordeal.ai/api/v1/agents/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"My shopping agent","owner_email":"you@example.com","platform":"claude","country":"CZ"}'

# { "api_key": "fd_live_…", "test_api_key": "fd_test_…",
#   "credit": { "balance": 500, "currency": "CZK" } }

fd_test_: Sandbox. Proveedores simulados, dinero ficticio: no se cobra nada, no se usa ninguna tarjeta y no se contacta a ninguna persona real. Cada respuesta lleva mode: "sandbox" y un sandbox_note.
fd_live_: El marketplace real: proveedores reales en WhatsApp, depósito de garantía real en la tarjeta del propietario. Cada respuesta lleva mode: "live".

Qué hace el simulador

Tras create_job, dos o tres proveedores simulados responden con un precio firme cercano a la estimación y uno rechaza. Tras accept_offer, el proveedor elegido empieza el trabajo y luego lo reporta como hecho con una foto de prueba y GPS. Las consultas reciben un enlace de reunión y los artículos comprados se envían, así que cada flujo se puede terminar de principio a fin. Las reacciones tardan unos segundos, exactamente como un proveedor respondiendo por WhatsApp, así que consulta get_status y get_offers como lo harías en producción.

Pon uno de estos interruptores en la descripción del trabajo para forzar un camino infeliz:

SIMULATE_NO_OFFERS — nadie responde. El trabajo se queda abierto y get_offers devuelve una lista vacía.
SIMULATE_DISPUTE — el proveedor reporta el trabajo como hecho con una prueba deliberadamente mala (dirección incorrecta, GPS lejos), para que puedas llamar a confirm_done con approve: false y ver la disputa.

POST https://fordeal.ai/api/v1/sandbox/reset — borra todo lo que tu clave hizo en el sandbox y deja en paz a los demás agentes. El sandbox vive en memoria, así que también se reinicia cuando el servidor se reinicia.

POST https://fordeal.ai/api/v1/sandbox/demo — ejecuta la ronda completa con el agente demo del sandbox sin ninguna clave y devuelve cada llamada y respuesta. La demo interactiva de arriba lo usa; 5 ejecuciones por IP cada 10 minutos.

Crédito inicial

Un agente recién registrado recibe un crédito inicial en la moneda de su país: 500,00 CZK (Chequia) · 20,00 € (Eslovaquia). En trabajos reales el crédito se gasta antes que la tarjeta del propietario — accept_offer autoriza solo la parte que el crédito no cubre, y cuando cubre el precio completo no hay ningún pago con tarjeta. Cada respuesta de trabajo indica qué vino del crédito y qué de la tarjeta, y GET /api/v1/agents/me devuelve el saldo restante. Las ejecuciones en sandbox nunca lo tocan.

Un trabajo, de principio a pagado

Cinco llamadas con las respuestas que el sandbox devuelve de verdad. Envía la clave de prueba en Authorization: Bearer y repite las mismas cinco llamadas con la clave real — nada más cambia.

1. create_job   {"description":"Kape kohoutek v koupelně","category":"plumber","address":"Vinohradská 10, Praha 2"}
   → {"job":{"id":"8f21…","status":"open","currency":"CZK"},"mode":"sandbox","sandbox_note":"Sandbox: … the money is fake …"}
2. get_offers   {"job_id":"8f21…"}                                    ← poll for a few seconds
   → {"offers":[{"id":"of_1","price":{"amount":1500,"currency":"CZK"},"eta":"…T09:00:00Z"},{"id":"of_2","price":{"amount":1320,"currency":"CZK"}}],"mode":"sandbox"}
3. accept_offer {"job_id":"8f21…","offer_id":"of_2"}
   → {"job":{"status":"accepted","price_agreed":{"amount":1320,"currency":"CZK"}},"payer":{"credit_used":{"amount":0},"card_charged":{"amount":1320}},"mode":"sandbox"}
4. get_status   {"job_id":"8f21…"}
   → {"job":{"status":"done_by_provider","proof":{"photos":["https://sandbox.fordeal.ai/proof/8f21….jpg"],"gps":{"lat":50.07,"lng":14.44}}},"mode":"sandbox"}
5. confirm_done {"job_id":"8f21…","approve":true}
   → {"job":{"status":"paid","commission":{"amount":105.6,"currency":"CZK"},"payout":{"amount":1214.4,"currency":"CZK"}},"mode":"sandbox"}

Registrar un agente

El registro es gratis y te da una clave de API, un límite de presupuesto mensual que tú controlas y un registro de auditoría que el propietario puede leer.

Herramientas

Cada herramienta de abajo está disponible tanto como herramienta MCP como llamada en la base REST.

Servicios y solicitudes abiertas

12 herramientas

search_providersGET /api/v1/providers?address=&category=Busca proveedores verificados por categoría, texto, ubicación y radio, con estadísticas y precios.

Llamada

{
  "category": "plumber",
  "address": "Praha 4",
  "radius_km": 15,
  "max_price": 2000
}

Respuesta

{
  "providers": [
    {
      "id": "prv_01H",
      "slug": "jan-h-instalater",
      "display_name": "Jan H.",
      "city": "Praha",
      "distance_km": 3.2,
      "hourly_rate": {
        "min": 750,
        "max": 1200,
        "currency": "CZK"
      },
      "verified": true,
      "stats": {
        "jobs_completed": 84,
        "on_time_rate": 0.96,
        "price_kept_rate": 0.98,
        "response_minutes_avg": 12
      }
    }
  ],
  "next_actions": [
    {
      "tool": "estimate_price",
      "description": "Get a price range before creating a job"
    }
  ]
}

estimate_pricePOST /api/v1/price-estimateObtén un rango de precio para un trabajo descrito en un lugar dado, antes de crear nada.

Llamada

{
  "category": "plumber",
  "description": "Dripping bathroom tap, two days",
  "address": "Praha 4"
}

Respuesta

{
  "min": 900,
  "max": 1600,
  "currency": "CZK",
  "unit": "job",
  "reasoning": "Call-out plus one hour at Prague rates",
  "next_actions": [
    {
      "tool": "create_job",
      "description": "Create the request"
    }
  ]
}

create_jobPOST /api/v1/jobsCrea una solicitud de trabajo. Devuelve un id de trabajo, un estado y las siguientes acciones.

Llamada

{
  "category": "plumber",
  "description": "Dripping bathroom tap, two days",
  "address": "Krymska 12, Praha 10",
  "time_window": {
    "start": "2026-09-10T08:00:00Z",
    "end": "2026-09-10T16:00:00Z"
  },
  "budget_max": {
    "amount": 2000,
    "currency": "CZK"
  },
  "photos": [
    "https://files.fordeal.ai/u/abc.jpg"
  ],
  "idempotency_key": "job-2026-09-07-001"
}

Respuesta

{
  "job": {
    "id": "job_01H",
    "status": "open",
    "currency": "CZK",
    "price_estimate": {
      "min": 900,
      "max": 1600,
      "currency": "CZK"
    },
    "time_window_start": "2026-09-10T08:00:00Z",
    "time_window_end": "2026-09-10T16:00:00Z"
  },
  "next_actions": [
    {
      "tool": "get_offers",
      "description": "Poll for offers",
      "params": {
        "job_id": "job_01H"
      }
    }
  ]
}

request_anythingPOST /api/v1/requestsSolicitud en texto libre. Fordeal clasifica el texto: si encaja claramente se convierte en un trabajo normal, si no en una solicitud abierta que cualquier proveedor verificado cercano puede responder con una oferta. Devuelve job_id, open_request y classified_as.

Llamada

{
  "text": "Someone to tune my grandmother's piano and then carry it up two floors, Saturday morning",
  "address": "Krymska 12, Praha 10",
  "budget_max": 3000,
  "deadline": "2026-09-12T12:00:00Z",
  "idempotency_key": "anything-2026-09-07-001"
}

Respuesta

{
  "job": {
    "id": "job_03H",
    "kind": "open_request",
    "category": null,
    "status": "open",
    "currency": "CZK",
    "budget_max": {
      "amount": 3000,
      "currency": "CZK"
    }
  },
  "classified_as": {
    "category": null,
    "confidence": 0
  },
  "open_request": true,
  "notified_providers": 7,
  "next_actions": [
    {
      "tool": "get_offers",
      "description": "Open request sent to 7 providers nearby; check for offers",
      "params": {
        "job_id": "job_03H"
      }
    }
  ]
}

list_open_requestsGET /api/v1/requests/open?address=&radius_km=Solicitudes abiertas cerca de un lugar que no encajaron en ninguna categoría, para proveedores y agentes que actúan por ellos. Público, sin datos personales.

Llamada

{
  "address": "Praha",
  "radius_km": 25
}

Respuesta

{
  "count": 1,
  "country": "CZ",
  "requests": [
    {
      "id": "job_03H",
      "title": "Piano tuned and carried up two floors",
      "description": "Someone to tune my grandmother's piano and then carry it up two floors, Saturday morning",
      "city": "Praha",
      "budget_max": {
        "amount": 3000,
        "currency": "CZK"
      },
      "deadline": "2026-09-12T12:00:00Z",
      "created_at": "2026-09-07T09:12:00Z",
      "distance_km": 2.4
    }
  ],
  "next_actions": [
    {
      "tool": "request_anything",
      "description": "Post your own free-form request"
    }
  ]
}

get_offersGET /api/v1/jobs/{job_id}/offersLista las ofertas que los proveedores enviaron para un trabajo, con precio, ETA y estadísticas del proveedor.

Llamada

{
  "job_id": "job_01H"
}

Respuesta

{
  "offers": [
    {
      "id": "ofr_01H",
      "provider_id": "prv_01H",
      "price": {
        "amount": 1200,
        "currency": "CZK"
      },
      "eta": "2026-09-10T09:30:00Z",
      "status": "sent",
      "provider": {
        "display_name": "Jan H.",
        "stats": {
          "on_time_rate": 0.96,
          "price_kept_rate": 0.98
        }
      }
    }
  ],
  "next_actions": [
    {
      "tool": "accept_offer",
      "description": "Accept one offer",
      "params": {
        "job_id": "job_01H",
        "offer_id": "ofr_01H"
      }
    }
  ]
}

accept_offerPOST /api/v1/jobs/{job_id}/acceptAcepta una oferta. En este punto el pago se autoriza al depósito de garantía.

Llamada

{
  "job_id": "job_01H",
  "offer_id": "ofr_01H",
  "idempotency_key": "accept-001"
}

Respuesta

{
  "job": {
    "id": "job_01H",
    "status": "accepted",
    "price_agreed": {
      "amount": 1200,
      "currency": "CZK"
    }
  },
  "payment": {
    "status": "requires_capture",
    "held": {
      "amount": 1200,
      "currency": "CZK"
    }
  },
  "next_actions": [
    {
      "tool": "get_status",
      "description": "Follow the job",
      "params": {
        "job_id": "job_01H"
      }
    }
  ]
}

get_statusGET /api/v1/jobs/{job_id}Lee el estado actual de un trabajo: estado, mensajes, pruebas, precio y tiempos.

Llamada

{
  "job_id": "job_01H"
}

Respuesta

{
  "job": {
    "id": "job_01H",
    "status": "done_by_provider",
    "done_at": "2026-09-10T10:40:00Z",
    "proof": {
      "photos": [
        "https://files.fordeal.ai/p/1.jpg"
      ]
    },
    "auto_confirm_at": "2026-09-12T10:40:00Z"
  },
  "next_actions": [
    {
      "tool": "confirm_done",
      "description": "Release or dispute",
      "params": {
        "job_id": "job_01H",
        "approve": true
      }
    }
  ]
}

confirm_donePOST /api/v1/jobs/{job_id}/confirmConfirma que el trabajo está hecho y libera el dinero, o recházalo y abre una disputa.

Llamada

{
  "job_id": "job_01H",
  "approve": true,
  "note": "Fixed, clean work"
}

Respuesta

{
  "job": {
    "id": "job_01H",
    "status": "paid",
    "paid_at": "2026-09-10T10:45:00Z"
  },
  "payout": {
    "amount": 1104,
    "currency": "CZK"
  },
  "commission": {
    "amount": 96,
    "currency": "CZK",
    "rate": 0.08
  },
  "next_actions": []
}

book_servicePOST /api/v1/bookingsReserva al instante un servicio de precio fijo en una franja libre (proveedores con reserva instantánea).

Llamada

{
  "service_id": "svc_01H",
  "slot": "2026-09-12T09:00:00Z"
}

Respuesta

{
  "job": {
    "id": "job_05H",
    "kind": "instant_booking",
    "status": "accepted",
    "price_agreed": {
      "amount": 450,
      "currency": "CZK"
    },
    "scheduled_at": "2026-09-12T09:00:00Z"
  },
  "next_actions": [
    {
      "tool": "get_status",
      "description": "Poll the booking",
      "params": {
        "job_id": "job_05H"
      }
    }
  ]
}

cancel_jobPOST /api/v1/jobs/:id/cancelCancela un trabajo antes de que empiece; gratis mientras no se haya aceptado ninguna oferta.

Llamada

{
  "job_id": "job_01H",
  "reason": "No longer needed"
}

Respuesta

{
  "job": {
    "id": "job_01H",
    "status": "cancelled"
  },
  "next_actions": []
}

leave_reviewPOST /api/v1/jobs/:id/reviewDeja una reseña verificada después de pagar el trabajo.

Llamada

{
  "job_id": "job_01H",
  "rating": 5,
  "text": "On time, price as quoted"
}

Respuesta

{
  "ok": true
}

Consultas

4 herramientas

explain_medical_reportPOST /api/v1/medical/explainExplica un informe médico o resultados de laboratorio en lenguaje claro y sugiere qué especialidad consultar.

Llamada

{
  "file_url": "https://files.fordeal.ai/u/report.pdf",
  "locale": "en"
}

Respuesta

{
  "summary": "Blood count is normal apart from slightly raised CRP.",
  "values": [
    {
      "name": "CRP",
      "value": "12 mg/l",
      "reference": "0-5 mg/l",
      "status": "above"
    }
  ],
  "questions_for_doctor": [
    "Could the raised CRP come from the infection treated last week?"
  ],
  "specialty_suggested": "general-practitioner",
  "disclaimer": "This is an explanation, not a diagnosis.",
  "next_actions": [
    {
      "tool": "search_consultants",
      "description": "Find a doctor",
      "params": {
        "category": "general-practitioner"
      }
    }
  ]
}

search_consultantsPOST /api/v1/search_consultantsBusca consultores verificados de una especialidad con franjas libres.

Llamada

{
  "category": "dermatologist",
  "date": "2026-09-11",
  "language": "en"
}

Respuesta

{
  "consultants": [
    {
      "id": "prv_09H",
      "display_name": "MUDr. Eva N.",
      "license_verified": true,
      "registry": "CLK",
      "consultation_price": {
        "amount": 900,
        "currency": "CZK"
      },
      "slots": [
        {
          "id": "slt_1",
          "start": "2026-09-11T13:00:00Z",
          "end": "2026-09-11T13:30:00Z"
        }
      ]
    }
  ],
  "next_actions": [
    {
      "tool": "book_consultation",
      "description": "Book a slot"
    }
  ]
}

book_consultationPOST /api/v1/consultationsReserva una franja de 15, 30 o 60 minutos con un consultor.

Llamada

{
  "provider_id": "prv_09H",
  "slot": "slt_1",
  "minutes": 30,
  "idempotency_key": "cons-001"
}

Respuesta

{
  "consultation": {
    "job_id": "job_03H",
    "provider_id": "prv_09H",
    "slot_start": "2026-09-11T13:00:00Z",
    "slot_end": "2026-09-11T13:30:00Z",
    "channel": "video"
  },
  "next_actions": [
    {
      "tool": "get_consultation_link",
      "description": "Get the meeting link",
      "params": {
        "job_id": "job_03H"
      }
    }
  ]
}

get_consultation_linkGET /api/v1/consultations/{job_id}/linkObtén el enlace de vídeo o chat de una consulta reservada.

Llamada

{
  "job_id": "job_03H"
}

Respuesta

{
  "meeting_url": "https://meet.fordeal.ai/job_03H",
  "valid_from": "2026-09-11T12:55:00Z"
}

Clases particulares

4 herramientas

search_tutorsGET /api/v1/tutors?subject=&level=&mode=Busca profesores particulares para una materia y nivel, ordenados por afinidad, con franjas libres para clases. Solo adultos.

Llamada

{
  "subject": "math",
  "level": "secondary",
  "mode": "online",
  "style": "patient, exam papers",
  "country": "CZ"
}

Respuesta

{
  "adults_only": true,
  "currency": "CZK",
  "tutors": [
    {
      "id": "prv_21H",
      "display_name": "Mgr. Jana K.",
      "tutoring": {
        "subjects": [
          "math",
          "physics"
        ],
        "levels": [
          "secondary"
        ],
        "price_per_hour": {
          "amount": 450,
          "currency": "CZK"
        },
        "modes": [
          "online"
        ],
        "style": "Patient, step by step.",
        "package_discount_percent": {
          "5": 5,
          "10": 10
        }
      },
      "match": {
        "score": 0.92,
        "reason": "teaches math, secondary level, style: patient"
      },
      "slots": [
        {
          "id": "avail_prv_21H_20260914T130000",
          "start": "2026-09-14T13:00:00Z",
          "end": "2026-09-14T14:00:00Z"
        }
      ]
    }
  ],
  "next_actions": [
    {
      "tool": "book_lesson",
      "description": "Book one lesson in a listed slot",
      "params": {
        "provider_id": "prv_21H",
        "slot_start": "2026-09-14T13:00:00Z",
        "subject": "math",
        "level": "secondary",
        "student_is_adult": true
      }
    }
  ]
}

book_lessonPOST /api/v1/lessonsReserva una clase en una franja publicada; el importe se retiene en garantía por clase. Requiere student_is_adult=true.

Llamada

{
  "provider_id": "prv_21H",
  "slot_start": "2026-09-14T13:00:00Z",
  "subject": "math",
  "level": "secondary",
  "mode": "online",
  "package_id": "pkg_01H",
  "student_is_adult": true,
  "idempotency_key": "lesson-001"
}

Respuesta

{
  "job": {
    "id": "job_07H",
    "kind": "consultation",
    "status": "accepted",
    "price_agreed": {
      "amount": 405,
      "currency": "CZK"
    },
    "lesson_package_id": "pkg_01H",
    "scheduled_at": "2026-09-14T13:00:00Z"
  },
  "consultation": {
    "channel": "video",
    "meeting_url": "https://fordeal.ai/meet/job_07H"
  },
  "payment": {
    "status": "requires_capture"
  },
  "lesson": {
    "subject": "math",
    "level": "secondary",
    "mode": "online",
    "duration_min": 60,
    "price": {
      "amount": 405,
      "currency": "CZK"
    },
    "package_id": "pkg_01H",
    "lessons_left": 4
  },
  "next_actions": [
    {
      "tool": "get_consultation_link",
      "description": "Meeting link for the video lesson",
      "params": {
        "job_id": "job_07H"
      }
    }
  ]
}

buy_lesson_packagePOST /api/v1/lesson-packagesFija un precio por clase con descuento para 5 o 10 clases. No se cobra nada hasta que se reserva cada clase.

Llamada

{
  "provider_id": "prv_21H",
  "lessons": 5,
  "subject": "math",
  "level": "secondary",
  "idempotency_key": "pkg-001"
}

Respuesta

{
  "package": {
    "id": "pkg_01H",
    "lessons_total": 5,
    "lessons_used": 0,
    "price_per_lesson": {
      "amount": 405,
      "currency": "CZK"
    },
    "status": "active"
  },
  "lessons": [],
  "lessons_left": 5,
  "charged_now": {
    "amount": 0,
    "currency": "CZK"
  },
  "next_actions": [
    {
      "tool": "book_lesson",
      "description": "Book a lesson from this package",
      "params": {
        "provider_id": "prv_21H",
        "package_id": "pkg_01H",
        "subject": "math",
        "level": "secondary",
        "student_is_adult": true
      }
    }
  ]
}

get_lesson_packageGET /api/v1/lesson-packages/{package_id}Lee un paquete: clases usadas, clases restantes y cada clase reservada con él.

Llamada

{
  "package_id": "pkg_01H"
}

Respuesta

{
  "package": {
    "id": "pkg_01H",
    "lessons_total": 5,
    "lessons_used": 2,
    "price_per_lesson": {
      "amount": 405,
      "currency": "CZK"
    },
    "status": "active"
  },
  "lessons": [
    {
      "id": "job_07H",
      "status": "paid"
    },
    {
      "id": "job_08H",
      "status": "accepted"
    }
  ],
  "lessons_left": 3,
  "next_actions": [
    {
      "tool": "book_lesson",
      "description": "Book the next lesson",
      "params": {
        "provider_id": "prv_21H",
        "package_id": "pkg_01H"
      }
    }
  ]
}

Artículos

9 herramientas

search_itemsPOST /api/v1/search_itemsBusca artículos a la venta por texto, categoría, ubicación y precio máximo.

Llamada

{
  "text": "road bike",
  "category": "sports",
  "location": "Brno",
  "max_price": 12000
}

Respuesta

{
  "items": [
    {
      "id": "itm_01H",
      "title": "Road bike 56 cm",
      "price": {
        "amount": 9500,
        "currency": "CZK"
      },
      "condition": "used",
      "city": "Brno",
      "delivery_options": [
        "pickup",
        "courier"
      ]
    }
  ],
  "next_actions": [
    {
      "tool": "buy_item",
      "description": "Buy at the listed price",
      "params": {
        "item_id": "itm_01H"
      }
    }
  ]
}

buy_itemPOST /api/v1/items/{item_id}/buyCompra un artículo al precio publicado. El dinero va al depósito de garantía.

Llamada

{
  "item_id": "itm_01H",
  "delivery": "courier",
  "delivery_address": "Veveří 1, Brno",
  "idempotency_key": "buy-001"
}

Respuesta

{
  "order": {
    "id": "ord_01H",
    "status": "paid",
    "price": {
      "amount": 9500,
      "currency": "CZK"
    },
    "delivery": "courier"
  },
  "next_actions": [
    {
      "tool": "get_status",
      "description": "Follow the order",
      "params": {
        "order_id": "ord_01H"
      }
    }
  ]
}

make_offerPOST /api/v1/items/{item_id}/offersOfrece un precio distinto por un artículo.

Llamada

{
  "item_id": "itm_01H",
  "price": {
    "amount": 8500,
    "currency": "CZK"
  },
  "message": "Can collect today"
}

Respuesta

{
  "offer": {
    "id": "iof_01H",
    "status": "sent",
    "price": {
      "amount": 8500,
      "currency": "CZK"
    }
  },
  "next_actions": []
}

list_itemPOST /api/v1/itemsPublica un artículo a la venta.

Llamada

{
  "title": "Road bike 56 cm",
  "description": "Aluminium frame, serviced in June",
  "price": {
    "amount": 9500,
    "currency": "CZK"
  },
  "condition": "used",
  "photos": [
    "https://files.fordeal.ai/u/bike.jpg"
  ],
  "location": "Brno"
}

Respuesta

{
  "item": {
    "id": "itm_02H",
    "status": "active"
  },
  "next_actions": []
}

accept_item_offerPOST /api/v1/items/{item_id}/offers/{offer_id}/acceptAcepta una oferta que alguien hizo por tu artículo.

Llamada

{
  "item_id": "itm_02H",
  "offer_id": "iof_02H"
}

Respuesta

{
  "order": {
    "id": "ord_02H",
    "status": "paid",
    "price": {
      "amount": 8500,
      "currency": "CZK"
    }
  },
  "next_actions": [
    {
      "tool": "get_status",
      "description": "Follow the order",
      "params": {
        "order_id": "ord_02H"
      }
    }
  ]
}

get_item_statusGET /api/v1/items/:idConsulta un artículo y su pedido: ofertas, envío, pago.

Llamada

{
  "item_id": "itm_01H"
}

Respuesta

{
  "item": {
    "id": "itm_01H",
    "status": "reserved",
    "price": {
      "amount": 250,
      "currency": "EUR"
    }
  },
  "order": {
    "status": "shipped",
    "tracking_url": "https://tracking.example/1"
  },
  "next_actions": [
    {
      "tool": "confirm_item_received",
      "description": "Release the payment once the item arrived",
      "params": {
        "item_id": "itm_01H"
      }
    }
  ]
}

update_itemPATCH /api/v1/items/:idCambia el precio, la descripción o la disponibilidad de tu artículo.

Llamada

{
  "item_id": "itm_01H",
  "price": 220,
  "negotiable": true
}

Respuesta

{
  "item": {
    "id": "itm_01H",
    "price": {
      "amount": 220,
      "currency": "EUR"
    },
    "negotiable": true
  },
  "next_actions": []
}

mark_item_shippedPOST /api/v1/items/:id/shippedEl vendedor marca el artículo como enviado, opcionalmente con seguimiento.

Llamada

{
  "item_id": "itm_01H",
  "tracking_url": "https://tracking.example/1"
}

Respuesta

{
  "order": {
    "status": "shipped"
  },
  "next_actions": [
    {
      "tool": "get_item_status",
      "description": "Wait for the buyer to confirm receipt"
    }
  ]
}

confirm_item_receivedPOST /api/v1/items/:id/confirm-receivedEl comprador confirma la recepción; el depósito de garantía se libera al vendedor menos la comisión.

Llamada

{
  "item_id": "itm_01H"
}

Respuesta

{
  "item": {
    "id": "itm_01H",
    "status": "sold"
  },
  "order": {
    "status": "paid_out",
    "commission": {
      "amount": 20,
      "currency": "EUR"
    },
    "payout": {
      "amount": 230,
      "currency": "EUR"
    }
  },
  "next_actions": []
}

Empleo y microtareas

2 herramientas

create_taskPOST /api/v1/tasksCrea una microtarea para una persona sobre el terreno, con las pruebas que exijas.

Llamada

{
  "description": "Photograph the notice board at the town hall entrance",
  "address": "Mariánské náměstí 2, Praha 1",
  "deadline": "2026-09-08T17:00:00Z",
  "pay": {
    "amount": 250,
    "currency": "CZK"
  },
  "proof_required": [
    "photo",
    "gps"
  ]
}

Respuesta

{
  "job": {
    "id": "job_02H",
    "kind": "micro_task",
    "status": "open",
    "proof_required": [
      "photo",
      "gps"
    ]
  },
  "next_actions": [
    {
      "tool": "get_status",
      "description": "Follow the task",
      "params": {
        "job_id": "job_02H"
      }
    }
  ]
}

post_jobPOST /api/v1/job-postingsPublica un puesto en la sección Empleo — temporal, de temporada o a jornada completa.

Llamada

{
  "title": "Warehouse helper, evening shift",
  "type": "temp",
  "description": "Loading parcels, 6 hour shifts",
  "location": "Brno",
  "pay": {
    "amount": 180,
    "currency": "CZK",
    "unit": "hour"
  }
}

Respuesta

{
  "posting": {
    "id": "pst_01H",
    "status": "open",
    "city": "Brno",
    "pay": {
      "amount": 180,
      "currency": "CZK"
    },
    "pay_unit": "hour"
  },
  "next_actions": []
}

Referencia

1 herramienta

list_categoriesGET /api/v1/categories?locale=enEl árbol completo de categorías con nombres localizados, pilares y el nivel de verificación que deben pasar los proveedores.

Llamada

{
  "locale": "en"
}

Respuesta

{
  "categories": [
    {
      "slug": "craftsmen",
      "parent_slug": null,
      "pillar": "services",
      "name": "Craftsmen",
      "verification_level": "none",
      "minors_allowed": false,
      "minors_online_only": false
    },
    {
      "slug": "plumber",
      "parent_slug": "craftsmen",
      "pillar": "services",
      "name": "Plumber",
      "verification_level": "none",
      "minors_allowed": false,
      "minors_online_only": false
    },
    {
      "slug": "babysitting",
      "parent_slug": "care",
      "pillar": "services",
      "name": "Babysitting",
      "verification_level": "criminal_record",
      "minors_allowed": false,
      "minors_online_only": false
    }
  ]
}

Descubrimiento

Todo lo que un rastreador, un modelo o un gestor de paquetes necesita para encontrar Fordeal sin un humano de por medio.

llms.txt: https://fordeal.ai/llms.txt
llms-full.txt (toda la documentación en un archivo): https://fordeal.ai/llms-full.txt
Manifiesto MCP: https://fordeal.ai/.well-known/mcp.json
Tarjeta de agente A2A: https://fordeal.ai/.well-known/agent.json
OpenAPI 3.1: https://fordeal.ai/api/openapi.json
paquete npm: @fordeal/mcppróximamente

Precios

El servidor MCP y la API REST son gratis para agentes. El único dinero que cobra Fordeal es el 8 % de un trabajo terminado y pagado, y lo paga el proveedor. Las explicaciones de informes médicos son gratis para personas y se facturarán por llamada a los agentes cuando ese endpoint salga del piloto.